Embeddable swap widget

Let your users swap without leaving your site. The Ophis widget is an iframe of swap.ophis.fi. Orders route through the Ophis solver and carry the Ophis partner fee automatically. It is a thin, Ophis-branded layer over the battle-tested CoW Protocol widget.

React (recommended)

npm install @ophis/widget-react react react-dom

import { OphisWidget } from '@ophis/widget-react';

export function Swap() {
  return (
    <OphisWidget
      params={{ tradeType: 'swap', width: '450px', height: '640px' }}
      onReady={() => console.log('Ophis widget ready')}
    />
  );
}

Pass a provider (an EIP-1193 injected wallet) to let users connect inside the widget. baseUrl, appCode, and the partner fee are injected for you.

Vanilla JS

No React? Use the underlying library and point it at Ophis:

npm install @cowprotocol/widget-lib @ophis/sdk

import { createCowSwapWidget } from '@cowprotocol/widget-lib';
import { buildOphisAppDataPartnerFee } from '@ophis/sdk';

const container = document.getElementById('ophis-widget')!;
const fee = buildOphisAppDataPartnerFee(10); // { volumeBps, recipient } on OP

createCowSwapWidget(container, {
  params: {
    baseUrl: 'https://swap.ophis.fi', // the Ophis host
    appCode: 'ophis',
    tradeType: 'swap',
    width: '450px',
    height: '640px',
    partnerFee: fee ? { bps: fee.volumeBps, recipient: fee.recipient } : undefined,
  },
});

The widget's partnerFee uses bps; the SDK exposes the same number as volumeBps. Map volumeBps to bps as shown.

Configuration

Field	Default (via @ophis/widget-react)	Notes
baseUrl	https://swap.ophis.fi	The iframe host. Override for a self-hosted/staging Ophis.
appCode	ophis	Tags orders in appData. Set it to a referral code you have minted and activated to earn the affiliate rebate on widget orders (an arbitrary label earns nothing).
partnerFee.bps	5 (0.05%, the SDK partner rate)	Same-chain stable pairs are reduced server-side.
partnerFee.recipient	Ophis Safe	Always pinned by the React wrapper.
chainId, sell, buy, theme, tokenLists	upstream defaults	Full CoW widget params pass through.

Theming

Pass a theme ('light' or 'dark') or a full palette object: see the upstream widget docs. The widget inherits the Ophis app styling by default.

Live demo + copy-paste snippets

A runnable demo and one-file snippets for React, Next.js, vanilla JS and a raw iframe live in the repo at examples/widget-embed/. Run npx serve . in that folder and open index.html to see the widget embedded against a third-party origin.

Notes

• The widget is GPL-3.0, like the rest of Ophis.
• Optimism and Unichain orders settle on the Ophis self-hosted orderbooks; the CoW-hosted chains (Ethereum, Base, Arbitrum, Polygon, BNB, Gnosis, Avalanche, Linea, Plasma, Ink) route via api.cow.fi. Host selection is handled inside the widget app, 12 chains in total.
• Self-hosting an Ophis fork? The host must allow third-party framing (CSP frame-ancestors *, no X-Frame-Options: SAMEORIGIN), or integrators' iframes are blocked. (swap.ophis.fi already ships this.) Clickjacking is mitigated structurally: every fund-moving action signs in a wallet popup outside the frame.
• For programmatic / agent integrations (no iframe), use the AI agent guide and @ophis/sdk directly.