> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rheon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Proposal: Integration & embedding

> Embed options, secure widget URL, chain/token filtering, and lifecycle events.

<Info>
  **Proposal, not live spec.** Patterns from how Transak, Li.Fi, MoonPay, and Coinbase
  Onramp let partners embed a widget. For team review.
</Info>

## Start with an "integration options" page

Every crypto on/off-ramp's docs open by making the partner choose a delivery model first.
Rheon could do the same:

| Option                                 | Pattern from                                                    | What you get                              |
| -------------------------------------- | --------------------------------------------------------------- | ----------------------------------------- |
| **Hosted iframe (overlay / embedded)** | MoonPay (`overlay` on top of page, `embedded` in a DOM element) | Fastest to ship, full widget              |
| **Web SDK**                            | Li.Fi `LiFiWidget` component                                    | Control over UI + lifecycle events        |
| **Redirect URL**                       | Transak, Coinbase hosted                                        | When you cannot embed (some mobile flows) |

Why: in crypto the delivery choice is the first decision, and devs get stuck when docs
don't lay out the trade-offs.

## Secure widget URL (recommended for white-label)

Pattern from **Transak**: instead of the client building a widget URL from raw query
params, the partner's backend calls a "Create Widget URL" API that returns a **signed**
`widgetUrl`. This prevents tampering with amount, target, or branding.

> Rheon fit: this matches white-label deposits where the host app must not be able to
> alter the deposit configuration client-side.

## Declarative chain / token filtering

Pattern from **Li.Fi** widget config - partners filter coverage declaratively:

* `chains.allow / deny`, `chains.from / to`
* `tokens.allow / deny / featured / popular`

Why it fits Rheon: the product is "any asset / any chain - USDC", so a partner will want
to restrict which chains/tokens their users see.

## Lifecycle events (for in-page UX)

Pattern from **Li.Fi** (`useWidgetEvents`, `WidgetEvent` enum). The widget emits events so
the host page reacts without polling. A Rheon set could be:

* `DepositStarted` - user confirmed, routing began
* `Routing` - settling cross-chain
* `SourceConfirmed` - source payment confirmed
* `Completed` - USDC landed
* `Failed` - deposit failed

> Important: events are for in-page UX only. Anything the backend must trust (crediting a
> user) goes through [webhooks](/proposals/webhooks), never a client event.

## Pre-fill parameters

Pattern from MoonPay / Transak - reduce screens by pre-filling: `walletAddress`, `email`,
`amount`, target chain/token. Each pre-filled field is one fewer screen for the user.