Skip to main content

Add to your Dapp (embeddable flow)

Surface on-chain options RFQs inside your Dapp with an iframe. Opshuns hosts the quote UI; your users connect a wallet and fill through your page. You earn referral fees when you pass your wallet in the iframe URL.

No API keys, no backend, and no on-chain integration code on your side. Only an iframe and a referral address.

When to use this​

PathChoose when
This embedFastest web Dapp path; hosted quote UI is fine; referral revenue is enough
Wallet API flowNative / in-wallet UX; you control layout; Turnstile-free quote create via taker org
TypeScript SDK + Call the CLOB / Settle matched intentsYou call contracts (or match) yourself

Architecture​

Your Dapp page
  └─ <iframe src="https://frame.opshuns.com/?referralAddress=0xYou…">
       └─ Opshuns Frame (hosted quote box)
            ├─ POST /api/quote  (public RFQ, referrer=0xYou…)
            ├─ WebSocket rfq_stream:<token>
            └─ User wallet → package fill with the same referrer

The trading app at app.* is not embeddable (X-Frame-Options: DENY). Always iframe frame.*, not app.*.

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 has to be the quote referrer (hashed into taker_address_hash) and the same address at fill. Invalid or missing addresses settle with referrer = address(0).

With the payoff diagram:

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

Hosts​

EnvironmentFrame URL
Productionframe.opshuns.com
Testnetframe.testnet.opshuns.com
Stagingframe.staging.opshuns.com
Localhttp://localhost:3005 (npm run dev:framed)

Point VITE_FRAME_URL at the matching host if you use the trading app’s landing-page embed preview.

Query parameters​

All flags are case-insensitive. Booleans accept true / false.

ParamDefaultEffect
referralAddressnone0x + 40 hex chars. Credited on fills through this embed.
sidebuybuy or sell. Alias: buySell.
typecallcall or put. Aliases: optionType, callPut.
strategysingleInitial structure (strangle, iron_condor, …). Alias: optionStrategy.
expirynext suggested weekYYYY-MM-DD or YYYY-MM-DDTHH:mm. Aliases: expiration, expiryDate.
amountemptyPrefills size (underlying units). Aliases: quantity, size. When set, Quote stays disabled longer before it arms.
strikeemptyPrimary strike (strikePrice alias), or strikes=90,110 / named fields. Works before a market is listed.
underlyingall listedSymbols or addresses for the underlying picker (WETH,WBTC). Alias: underlyingTokens.
quoteall listedSymbols or addresses for the pair quote picker. Aliases: quoteTokens, pairQuote.
premiumall payment / listedSymbols or addresses for the premium picker. Alias: premiumTokens.
showPayoffDiagramfalsetrue shows the options payoff diagram beside the quote box.
tooltipstruefalse hides hover help (useful in a short iframe).
langbrowser / EnglishUI language (de, ja, zh-TW, …). Alias: locale.

Restrict which tokens appear​

Limit the underlying, pair quote, and premium pickers from the iframe URL. Full walkthrough: Embed the quote box → Restrict which tokens appear.

FieldParamExample
Underlyingunderlyingunderlying=WETH,WBTC
Pair quotequotequote=USDC
Premiumpremiumpremium=USDC

Comma-separated symbols or 0x addresses; first value is the default. Aliases: underlyingTokens, quoteTokens / pairQuote, premiumTokens.

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

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&strategy=strangle
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&underlying=WETH&quote=USDC&premium=USDC
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&showPayoffDiagram=true
https://frame.opshuns.com/?referralAddress=0xYOURADDRESS&lang=de

Referral fees​

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

FeeDefaultBasis
Premium referral19.53 bps (1/512)Option premium
Underlying referral1.22 bps (1/8192)Trade notional

Full schedule and who pays: Protocol & referral fees.

The Frame reads referralAddress from the URL. That value is the quote referrer and must be passed again at fill. You do not sign the maker quote. A different address at fill reverts.

Sizing​

Recommended: 480×800 (quote only) or 780×800 (with payoff). See Embed the quote box for minimums and layout notes.

Give the iframe enough height for the expiry calendar and offer list. If you use sandbox, include allow-popups so wallet connect / WalletConnect can open.

Host page checklist​

  • CSP: allow frame-src (or child-src) for https://frame.opshuns.com (or your environment host).
  • Wallet popups: injected wallets and WalletConnect open outside the iframe; do not block popups.
  • No cookies required: referrerPolicy="strict-origin-when-cross-origin" is enough.
  • Frame ancestors: Frame allows any parent (frame-ancestors *).

What traders get​

Same quote box as the trading app: amount, underlying, premium token, expiry, strategy picker, RFQ offers, and wallet connect. Spreads: Option spreads.

Local development​

npm run dev:framed

Embed http://localhost:3005/?referralAddress=0xYOURADDRESS. The Frame uses the same API / RPC as trading (VITE_API_URL, etc.).