> For the complete documentation index, see [llms.txt](https://pharos-production.gitbook.io/gambit-stream-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pharos-production.gitbook.io/gambit-stream-docs/sportsbook-iframe-wallet-handoff-runbook.md).

# A Sportsbook Iframe Needs a Wallet Handoff Runbook

Use four responsibility lanes and a six-step wallet handoff for a fictional interrupted iframe session. Preserve unknown outcomes and action authority.

<figure><img src="https://content.gitbook.com/content/Fj51FabMWkruFqGwV9u5/blobs/LLTqy1JYCetznYDM5QZK/assets/cover.png" alt="Gambit Stream proposed sportsbook iframe handoff: operator host, iframe supplier, wallet owner and receiving coordinator have distinct evidence and decisions." width="1440"><figcaption><p>Proposed responsibility map. No operator session or wallet recovery exercise was run.</p></figcaption></figure>

## Start with the decision the next team must own

The sportsbook iframe reconnects and the player can see markets again. The operator's support ticket still concerns a wallet request whose result is unavailable. The supplier reports that its interface submitted the request. The wallet team has not supplied an authoritative result. Passing the ticket to another shift should preserve that unanswered question, together with the person responsible for obtaining its next observation.

A wallet handoff runbook connects operating responsibility to evidence and permitted actions. It should explain who can restore access, who can inspect the iframe exchange and who can resolve the financial operation.

A receiving coordinator can accept the investigation while its financial result remains unresolved. That distinction belongs in the handoff record and in the release criteria.

The runbook below is proposed documentation for a fictional interruption H-131. Its identifiers, notifications and unavailable records are supplied scenario inputs. No operator session, browser integration, wallet transaction or recovery exercise was run. Each expected observation describes evidence to request during an agreed exercise, rather than a completed test result.

[Gambit Stream's sportsbook iframe integration](https://gambitstream.com/sportsbook-iframe/) connects an embedded sportsbook to an operator's existing wallet and player sessions. That boundary makes the handoff responsibilities worth agreeing before implementation. The offer description does not establish that a particular supplier can replay requests, export every required record or resolve an unknown wallet outcome.

## Draw four responsibility lanes before writing steps

Begin with a responsibility swimlane that names the operator host, iframe supplier, wallet owner and receiving coordinator. These are roles, not a mandatory organization chart. One team may hold several roles, but each decision still needs an identifiable authority. A contact address alone does not say whether its recipient may retrieve evidence, authorize a new effect or accept an unresolved case.

| Responsibility lane   | Evidence it supplies                                                    | Decision it owns                                                | Limit carried into handoff                                   |
| --------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------ |
| Operator host         | Player access state and operator-side request references                | Permitted player access and affected workflow controls          | Restored access does not resolve a wallet operation          |
| Iframe supplier       | Interface revision, message trace and supplier-side request association | Supplier interface diagnosis and its contract-specific response | A browser notification alone is not ledger confirmation      |
| Wallet owner          | Authorized operation lookup and retained financial result               | Financial result interpretation and permitted wallet action     | Unavailable readback leaves the outcome unresolved           |
| Receiving coordinator | Handoff acknowledgement, accessible evidence links and open tasks       | Coordination transfer and next review ownership                 | Accepting the case does not grant financial action authority |

Place the required decision beside the role rather than beside a broad component name. An engineer responsible for the host page may diagnose a missing event listener without being allowed to dispatch a wallet request. An on-call coordinator may arrange a supplier review without being able to read restricted financial records. The runbook needs an authorized route to each role's evidence.

Where the supplier and operator have different support hours, record the agreed escalation route and its coverage. Do not invent a response commitment to fill an empty field. An unanswered contact dependency is a preparation task that can block an exercise or leave a receiving team unable to continue the investigation.

## Build a retrievable evidence envelope

Create one incident or work reference for coordination, then link it to the original business operation. For H-131, use coordination reference H131, launch reference F131 and wallet operation reference OP131. The references are illustrative. The actual integration must define how its provider namespace, account, wallet and currency identify the relevant request.

Record the interface contract revision and the source of each observation. A host log, supplier export and wallet lookup can describe different stages of the same exchange. Label what each source actually establishes, including whether it reports a request, a response or a retained result. Keep the time observed separate from any source timestamp whose clock or offset has not been established.

The envelope should point to permitted evidence locations rather than copy every payload into a shared ticket. Use nonsecret correlation references and the access rules agreed for reviewers. Credentials and sensitive account material belong in the designated restricted system. A receiving coordinator can request an authorized review without acquiring access to every underlying record.

Include the missing evidence as an explicit entry. In H-131 the original operation reference is available, but the wallet result cannot yet be read. That is different from having no operation identity at all.

The first case needs a restored lookup route; the second also needs a reliable way to identify the target.

Their next owners and stop conditions can differ.

A useful envelope also preserves the last proposed action and why it was withheld. If a previous shift decided that another dispatch required wallet review, carry that decision forward with its basis.

Assigning the ticket to a new person should not silently remove the restriction or replace OP131 with a fresh operation reference.

Keep coordination history append-only in the agreed evidence record. The current owner can add a new assignment, observation or decision without erasing the basis of the previous handoff. The implementation need not expose every restricted detail to every role. It does need a permitted way for the reviewer to reconstruct which evidence was available when a particular action was approved or withheld.

Distinguish an unavailable source from a source that returns no matching record. Both require interpretation under the actual lookup contract. An empty search through a limited export may establish only that the export contains no match. Ask the evidence owner to state its coverage, revision and access limit before using that observation to resolve OP131. The handoff should retain that scope next to the result.

## Walk through interruption H-131 without inventing closure

<figure><img src="https://content.gitbook.com/content/Fj51FabMWkruFqGwV9u5/blobs/46zgILuBosQSgh2xVoCM/assets/handoff.png" alt="Fictional H-131 handoff. Preserve OP131, assess the permitted hold, obtain supplier evidence, request wallet readback and acknowledge coordination. Wallet result remains unknown and financial action stays held unless its authorized review supports it. No test was run." width="1440"><figcaption><p>Fictional H-131. Coordination may be accepted while the financial outcome and affected action remain unresolved.</p></figcaption></figure>

Assume the operator has launched iframe instance F131 for an authorized player interaction. Its configured supplier origin and interface revision are known in the proposed setup. The iframe emits a contract-defined submitted notification N131 associated with OP131. The host then loses the interface connection before obtaining the result needed to complete the player's workflow.

The scenario deliberately leaves the financial outcome unknown. It does not assume a committed debit, a rejected request or a provider acknowledgement. The wallet owner cannot retrieve the authoritative OP131 result at the handoff point. The next shift receives the retained references and the unresolved evidence task, rather than a conclusion derived from the interface's return to service.

The operator may restore the player's access through the normal authorization path. That can be recorded as a separate access outcome. A reload of F131, or creation of a later frame instance, must follow the agreed integration behavior.

Neither event independently authorizes another financial request. Any automatic action triggered by reconnect needs its own explicit contract and acceptance evidence.

Propose a scoped hold on the affected automatic dispatch while its eligibility remains unresolved, but first verify that the implementation supports such a control. If it cannot isolate OP131, the runbook needs an approved fallback and an authorized decision owner.

A document cannot create a safe per-operation control by naming one that the application does not have.

At handoff, the receiving coordinator acknowledges H131 and accepts the task of obtaining the wallet readback through its owner. This is a proposed acknowledgement, not a real sign-off. The case can be administratively transferred while its affected financial decision stays held. The acceptance record should make both states visible.

## Treat browser messages as evidence of their own exchange

A cross-origin message can connect the operator host and the embedded interface, but its trust checks need to be specified. [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) gives this instruction for postMessage:

> Always specify an exact target origin, not \*, when you use postMessage to dispatch data to other windows.

For received messages, define the expected sender identity and validate the permitted message structure. MDN describes checking origin and, where applicable, source. In an iframe integration, the team should establish how the sender is associated with the intended frame instance. This is a browser messaging requirement, not a provider-specific financial acceptance rule.

The [OWASP HTML5 Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html) also recommends validating origin and message data, and treating exchanged messages as data rather than executable code. Give the host implementation an exact allowed-origin policy and an agreed schema. A loosely matching domain fragment is insufficient evidence that a notification came from the intended sender.

A correctly validated N131 can establish that the host received that notification under the agreed message contract. It does not independently establish what the wallet recorded. The supplier must explain the notification's meaning and its relationship to server-side evidence. Record that limit instead of letting a label such as submitted become an undocumented synonym for financially complete.

Keep browser diagnostic evidence bounded. The runbook needs enough information to identify the relevant document instance, contract version and message association. It does not need a general instruction to retain every browser event or expose tokens in an incident channel. The evidence owner should specify a permitted export with the required fields and access controls.

## Make each operating step end in an inspectable condition

Write steps with entry conditions and an observable exit. Avoid instructions that depend on someone remembering a private conversation with the supplier. The table proposes a six-step route for H-131. Its rows assign work; they do not demonstrate execution or authorize actions outside the actual integration contract.

| Proposed step                   | Responsible role                   | Evidence or input required                              | Exit condition and remaining limit                                           |
| ------------------------------- | ---------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Open the affected case          | Operator host owner                | H131 with original F131 and OP131 references            | Coordination record exists; financial outcome still unknown                  |
| Assess dispatch eligibility     | Authorized operator decision owner | Contract rules and available affected-workflow controls | Permitted hold or approved fallback recorded; no new effect inferred         |
| Collect interface evidence      | Iframe supplier                    | Revision, intended origin and N131 association          | Supplier trace is retrievable; its financial claim boundary is stated        |
| Request operation readback      | Wallet owner                       | Authorized lookup route for original OP131              | Known result with evidence, or explicit unavailable status                   |
| Transfer coordination           | Receiving coordinator              | Readable envelope, open tasks and named evidence owners | Receiver acknowledges responsibility; unresolved financial decision retained |
| Review the affected next action | Authorized decision owner          | Applicable contract and sufficient current evidence     | Action approved within scope, or hold and next review preserved              |

The readback step has more than one valid exit. It may supply an authoritative result, or it may establish that the result cannot yet be retrieved.

The latter is useful information when its scope and owner are recorded. It should not be rewritten as a rejection simply to move the case through a status board.

Before any permitted dispatch, confirm the original identity and the contract governing repeated requests.

The coordinator's acknowledgement is not that confirmation. A repair to the host listener is not that confirmation either. If another financial effect or correction is needed, it requires its own authorized decision and evidence linking it to the original case.

Where a result can be recovered without another financial request, separate that read or response-recovery work from mutation. Identify who can perform it and what information may be returned to the player. The distinction helps the receiving shift restore useful visibility while preserving the unresolved action boundary.

## Verify that the receiver can continue the investigation

Handoff acceptance should include an access check. The outgoing engineer may be able to open a supplier trace that the next shift cannot see. Ask the receiving role to locate the permitted evidence and identify the owner of any restricted review. A link copied into a ticket is only a pointer until the intended reviewer can use it.

Record the scope of the acknowledgement. In H-131, a coordinator can accept responsibility for requesting wallet evidence while the financial outcome remains unknown. The acknowledgement should identify the next task, its owner and the next review point. It should also preserve which decision remains withheld.

A broad accepted label can conceal each of those distinctions.

If the receiving team rejects the handoff because evidence is unavailable, keep the current coordination owner explicit. Route the access problem as a named dependency rather than leave both shifts assuming the other is responsible. The operating agreement should define who retains coordination until a receiver actually acknowledges the case.

A handoff deadline helps organize work, but it cannot turn missing evidence into permission to retry. The next review might obtain a known result, discover an identity conflict or continue the escalation. Record the observed change and its source. If nothing substantive changed, keep the outcome unresolved and identify the next justified investigation step.

A practical acknowledgement can carry four named fields: coordination reference, accepted task, receiving owner and decision still withheld. For fictional H131, the task is to obtain the wallet readback for OP131; the withheld decision is eligibility for another affected financial dispatch. Add the permitted evidence route and review point under the operating agreement. This is a proposed record format, not evidence that a real person accepted the task.

Make the outgoing owner confirm the same scope. If one shift believes it transferred financial approval while the other accepted only access diagnosis, both can act on incompatible assumptions. The acknowledgement exchange should expose that difference before the outgoing team relinquishes coordination. A receiving engineer should be able to name the original operation and explain which decision they are expected to obtain, without contacting the previous presenter for missing context.

## Separate closure of access, coordination and financial work

A support case can contain several work items with different acceptance evidence. The host team may restore player access. The supplier may repair a browser notification defect. The wallet owner may later recover an operation result. Those events can happen on different schedules, and each should be recorded under the responsibility it actually resolves.

For H-131, propose three explicit closure questions. Has the receiving coordinator accepted the open investigation? Has the relevant interface or access issue met its agreed completion check? Has the affected financial outcome been established and its next action approved where required? A yes to one question should leave the unanswered questions visible.

Keep administrative closure separate from player-facing statements. A ticket moved to another queue does not justify telling a player that a transaction failed or completed. The operator needs an approved communication route that reflects the evidence available at that point. This runbook supplies no universal player message or promise about when the missing result will appear.

Escalation should preserve the original envelope rather than start a new unlinked investigation. Add the new owner, requested evidence and response when it becomes available. If a supplier statement conflicts with the retained wallet record, keep both observations and assign the reconciliation question. Do not overwrite an earlier source merely because the latest message sounds more confident.

## Rehearse the handoff with explicit unrun cases

The proposed acceptance pack should exercise handoff failure as well as reconnect behavior. Agree permitted inputs and the evidence expected from each lane. All seven cases below remain unrun. Their relevance and execution method must be confirmed against the real host, supplier tools and wallet design before an acceptance session is booked.

| Proposed case                  | Input to agree                                       | Observation to request                                                 | Acceptance boundary                                      |
| ------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------- |
| Missing wallet response        | Interrupt the permitted response path                | Original operation reference and authoritative readback route retained | No financial outcome inferred from timeout               |
| Interface restored first       | Restore the approved player interface path           | Access outcome separate from OP131 investigation                       | Reconnect does not authorize a new effect                |
| Message from unexpected origin | Supply an approved invalid-origin fixture            | Host rejects processing under the defined policy                       | Fixture scope does not establish full security assurance |
| Late message from old instance | Deliver the agreed retained notification             | Intended instance and original operation association checked           | Latest frame is not assumed to own the old message       |
| Result lookup unavailable      | Make the permitted lookup route unavailable          | Explicit unavailable status and evidence owner                         | No guessed rejection or success                          |
| Receiver lacks evidence access | Use a receiving role without a required review route | Access dependency and retained coordination owner recorded             | Handoff not silently treated as accepted                 |
| Coordination restarts          | Restart the agreed support workflow                  | Original references, held decision and owner history recoverable       | No fresh operation identity created by ticket restart    |

For each exercise, preserve expected and actual observations separately. The reviewer should be able to trace an accepted claim to its source. A browser screenshot may show restored access, while a wallet result requires a different observation. The exercise report should state which parts were demonstrated and which remain blocked or outside the agreed scope.

## Keep the runbook attached to the released contract

Version the runbook with the interface and adapter revisions it describes. A changed notification schema, sender origin or repeated-request rule can invalidate an operating step. Identify the affected rows and the evidence needed before adopting the revision. A document that remains available after a release is not necessarily applicable to that release.

Include rollback and open-work ownership in the release handoff. Reverting an interface build may leave OP131 unresolved under the original connection. The receiving team needs the applicable lookup route and the owner of that retained work. A software rollback should not be recorded as financial reconciliation unless the actual evidence supports that conclusion.

Assign a maintenance owner who can review changed support contacts, evidence access and supplier procedures. A previous handoff exercise does not establish that the next shift still has the necessary permissions. Keep these dependencies inspectable in the runbook so a release review can identify a missing operating capability before relying on it.

Maintain a small change note for the runbook itself. State which responsibility, evidence route or stop condition changed and who approved its adoption. Retain the previous version with the cases it governed. During an investigation, the team can then use the version applicable to the original exchange while separately reviewing whether the new procedure can safely apply to any remaining work.

## Commission a usable operating handoff

Ask the integration supplier to separate implementation deliverables from operating readiness. A useful work package can name the responsibility map, evidence envelope, supported workflow controls and agreed exercise report. Supplier exports, wallet lookup access and receiving-team availability should appear as explicit inputs. Their absence should remain visible rather than disappear inside a broad support promise.

Gambit Stream's iframe integration scope is a relevant starting point for agreeing that work around an existing operator wallet. Apply the same evidence requirements to its proposed handoff as to any other supplier's deliverables. A service description is evidence of an offering, not proof that H-131 or another recovery case has passed acceptance.

The proposed final record for H-131 retains OP131, an unknown financial outcome and the task of obtaining an authorized wallet readback. The receiver can accept coordination with those limits stated. The next commitment is a named evidence request and its receiving owner, followed by an action decision justified by the actual contract and result.

## More insights to read

* [How to Specify Casino Provider Onboarding Acceptance](https://gambitstream.wordpress.com/2026/10/31/how-to-specify-casino-provider-onboarding-acceptance/)
* [How to Define a Casino Provider Sandbox Acceptance Plan](https://dmytronasyrov.substack.com/p/casino-provider-sandbox-acceptance-plan)
* [Game Launch Acceptance: Player, Currency and Session Boundaries](https://gambitstream.wordpress.com/2026/11/04/game-launch-acceptance-player-currency-and-session-boundaries/)
* [Casino Wallet Recovery: Keep Session, Round and Ledger State Separate](https://pharos-production.hashnode.dev/casino-wallet-recovery-session-round-ledger-state)
* [Sportsbook iFrame Integration: Test Reconnects Against the Original Wallet Operation](https://dev.to/gambit_stream/sportsbook-iframe-integration-test-reconnects-against-the-original-wallet-operation-2i82)

## About the author

<figure><img src="https://content.gitbook.com/content/Fj51FabMWkruFqGwV9u5/blobs/Fds6XJ1alx4qPl6dfhea/assets/author.jpg" alt="Portrait of Dmytro Nasyrov wearing a dark suit and light blue shirt against a dark background." width="128"><figcaption><p>Dmytro Nasyrov. Photo supplied by the author.</p></figcaption></figure>

*Written by* [*Dmytro Nasyrov*](https://pharosproduction.com/dmytro-nasyrov/) *PhD, software architect with 24 years of production experience. Dmytro is the founder of Gambit Stream. His writing covers software scope, integration boundaries and operating ownership.*