Embed the quote box (Frame)

:::tip Integration guide For a Dapp-focused walkthrough (when to embed vs API, referral setup, CSP), see Add to your Dapp. For bots and custom UIs, see TypeScript SDK. :::

Drop the Opshuns quote box into any site with an iframe. Traders get quotes and fill through your page; you can take a referral fee on those fills.

Hosts:

Environment	URL
Production	frame.opshuns.com
Testnet	frame.testnet.opshuns.com
Staging	frame.staging.opshuns.com
Local	http://localhost:3005

The trading app landing page includes a live preview and a copy-paste snippet. Point VITE_FRAME_URL at the matching host so that preview is correct.

Quick start

<iframe
  src="https://frame.opshuns.com/?referralAddress=0xYOURADDRESS"
  width="480"
  height="800"
  style="border:0;border-radius:12px;"
  title="Opshuns"
></iframe>

Replace 0xYOURADDRESS with the wallet that should receive referral fees. It is the quote referrer inside taker_address_hash, and the fill must pass the same address. Invalid or missing addresses are ignored (no referral).

With the payoff diagram, use a wider frame:

<iframe
  src="https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&showPayoffDiagram=true"
  width="780"
  height="800"
  style="border:0;border-radius:12px;"
  title="Opshuns"
></iframe>

Query parameters

All flags are case-insensitive. Boolean params accept true / false.

The same params also work on the trading app at / and /trade (see Trading app). On the app, showPayoffDiagram defaults to on; on the Frame it defaults to off.

Param	Default	Effect
referralAddress	none	0x + 40 hex chars. Credited on fills that go through this embed.
side	buy	buy or sell. Aliases: buySell; also accepts long / short / write.
type	call	call or put (singles). Aliases: optionType, callPut.
strategy	single	Initial option structure: single, straddle, strangle, butterfly, condor, iron_butterfly, iron_condor, risk_reversal, collar. Hyphens allowed (iron-butterfly). Alias: optionStrategy. Invalid values fall back to single.
expiry	next suggested week	Expiry date: YYYY-MM-DD, YYYY-MM-DDTHH:mm, MM/DD/YYYY, or unix seconds. Aliases: expiration, expiryDate.
amount	empty	Prefills the size field (underlying units). Aliases: quantity, size. When set, the Quote button stays disabled longer before it can be clicked.
strike	empty	Primary strike for the active strategy (also strikePrice). Named: putStrike, callStrike, lowStrike, … Or strikes=90,110 in strategy field order. Works even when that market is not listed yet.
underlying	all listed	Comma-separated symbols or addresses for the underlying picker. Alias: underlyingTokens.
quote	all listed	Comma-separated symbols or addresses for the pair quote picker. Aliases: quoteTokens, pairQuote.
premium	all payment / listed	Comma-separated symbols or addresses for the premium picker. Alias: premiumTokens.
showPayoffDiagram	false	true shows the options payoff diagram beside the quote box.
tooltips	true	false hides all hover help (useful in a short iframe).
lang	browser / English	UI language (de, ja, zh-TW, …). Alias: locale.

Restrict which tokens appear

Use these params when your Dapp should only offer certain assets (for example WETH options settled in USDC). Omit a param to leave that picker unrestricted.

Field in the quote box	Query param	Example
Underlying (asset)	underlying	underlying=WETH,WBTC
Pair quote (strike / settlement units)	quote	quote=USDC
Premium paid in	premium	premium=USDC

How to write them:

1. Append to the iframe src as usual query string params (after referralAddress, etc.).
2. Pass one or more tokens per field, separated by ,, +, or |.
3. Each entry can be a symbol (WETH), registry key (weth), or contract address (0x…). Matching is case-insensitive.
4. List order is the default selection (first match is pre-selected).
5. If a list matches nothing on the selected network, the Frame keeps the full picker so a typo does not brick the embed.

Aliases: underlyingTokens, quoteTokens / pairQuote, premiumTokens.

<iframe
  src="https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&underlying=WETH,WBTC&quote=USDC&premium=USDC"
  width="480"
  height="800"
  style="border:0;border-radius:12px;"
  title="Opshuns"
></iframe>

Single-asset embed (only WETH, quote and premium both USDC):

https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&underlying=WETH&quote=USDC&premium=USDC

Examples:

https://frame.opshuns.com/?referralAddress=0xYOURADDRESS
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&side=sell&type=put
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&expiry=2026-12-31&strike=3500
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&amount=1.5&strike=3500&type=call
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&strategy=strangle&strikes=3000,4000&expiry=2026-06-30T15:00
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&strategy=strangle
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&underlying=WETH,WBTC&quote=USDC&premium=USDC
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&showPayoffDiagram=true
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&showPayoffDiagram=false&tooltips=false
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&lang=de

Referral fees

On fills that include a valid referralAddress, referral fees are additive on top of protocol fees:

Fee	Default	Basis
Premium referral	19.53 bps (1/512)	Option premium
Underlying referral	1.22 bps (1/8192)	Trade notional

Full protocol + referral schedule, who pays, and when: Fees.

The address is the quote referrer. Settlement must pass that same address. Use your own wallet, not the 0xYOURADDRESS placeholder. Rates: Fees.

Sizing

Recommended iframe size (leave room for the strategy picker, expiry calendar, and offer list):

Layout	Width	Height
Quote box only	480	800
Quote box + payoff (showPayoffDiagram=true)	780	800

Minimum usable size is about 420×740, but the recommended sizes above avoid clipping controls and quotes. Use scrolling="no" if the host clips scrollbars. Prefer tooltips=false only when the frame is too short for hover help.

The widget content is ~34rem (~544px) wide for the quote box alone; with payoff, plan for roughly 24rem + gap + 34rem.

What traders see

Same quote box as the trading app: amount, underlying, premium token, expiry (American / European), strategy picker, RFQ offers, and wallet connect. Spreads work as in Option spreads.

Wallet popups (injected wallets / WalletConnect) open outside the iframe. Do not sandbox the iframe in a way that blocks those popups (allow-popups if you use sandbox).

Host page notes

• The frame allows any parent (frame-ancestors *). Your page does not need a special CSP to contain it; you only need to allow the frame src (usually frame-src https://frame.opshuns.com).
• The trading app itself is not embeddable (X-Frame-Options: DENY). Always iframe frame.*, not app.*.
• referrerPolicy="strict-origin-when-cross-origin" is enough; the widget does not need extra cookies.

Local development

npm run dev:framed

Open http://localhost:3005 or embed:

<iframe
  src="http://localhost:3005/?referralAddress=0xYOURADDRESS&showPayoffDiagram=true"
  width="780"
  height="800"
  style="border:0;border-radius:12px;"
  title="Opshuns"
></iframe>

The framed app talks to the same API / RPC as trading (VITE_API_URL, etc.). Run the API locally if you want live quotes.

Related

• Quote box behavior: Trading app
• Strategies: Option spreads
• Fees: Protocol & referral fees
• RFQ payloads: Option spread quotes