Define the trust boundary around an embedded swap widget

Embedding a swap widget creates an interface boundary, not an automatic transfer of every responsibility to the widget vendor. The host must decide what data crosses that boundary and which messages can affect its own state.

Start with the embedding model

A same-page JavaScript component runs within the host's execution environment. An iframe can provide an origin boundary, but any messaging channel reintroduces an explicit communication surface. Document which model the integration uses before selecting controls.

For iframe messaging, MDN's postMessage documentation calls for explicit target origins and validation of incoming origin, source and message structure. A familiar event name is not sufficient authentication.

Limit the message contract

Define allowed messages such as initialized, quote displayed, transaction submitted and settlement observed. Validate their schema and associate them with a widget instance and attempt identifier. Ignore unexpected messages rather than forwarding arbitrary payloads into wallet calls.

Do not expose backend API secrets through widget configuration or messaging. Only pass credentials intended for public client use, with the restrictions required by the provider.

Separate notifications from evidence

A widget's success event may mean submission, provider acceptance or confirmed settlement. Agree on its exact meaning. If the host grants access, updates an account balance or records a payment outcome, verify the relevant chain or order evidence independently.

Keep wallet connection and signing authority clear. The host should not open a second approval flow in response to a widget error unless that workflow is explicitly part of the integration.

Plan for removal

Unmounting the widget should remove event listeners and stop creating new wallet requests. It should not erase transaction references needed for follow-up. Test an event from the wrong origin, a stale widget instance and a duplicate settlement notification; none should create a second host-side outcome.