@ordanetwork/widget

Drop-in React widget for Orda payments — wraps the Orda SDK with wallet connection, quote flow, and on/off-ramp UI.

Status: stable. Versioned with semver; breaking changes ship only in major releases.

Install

npm install @ordanetwork/widget @ordanetwork/sdk
# peers
npm install react react-dom @tanstack/react-query wagmi viem

Quick start

'use client';

import {
  OrdaProvider,
  Widget,
  createAppKitConfig,
} from '@ordanetwork/widget';
import '@ordanetwork/widget/styles.css';

const appKitConfig = createAppKitConfig({
  projectId: process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID!,
});

export default function Page() {
  return (
    <OrdaProvider
      config={{
        getToken: async () => {
          const res = await fetch('/api/auth/jwt', { method: 'POST' });
          return res.json(); // { jwt: string, expiresAt: number }
        },
        appKitConfig,
        // Feature flags (all optional, default false):
        disableOnRamp: false,
        disableOffRamp: false,
        enableOfframpSolana: false,
      }}
    >
      <Widget
        onQuoteRequested={(e) => console.log('quote requested', e)}
        onTransactionSettled={(e) => console.log('settled', e)}
        onError={(e) => console.error(e.payload.message)}
      />
    </OrdaProvider>
  );
}

<Widget /> lifecycle callbacks

All callbacks are optional. Use the typed callbacks for product logic; use onAnalyticsEvent to stream every event to your analytics tool in one place (see onAnalyticsEvent).

| Callback | Fires when | | --- | --- | | onQuoteRequested | The widget asked the SDK for a quote (before network round-trip). | | onQuoteAccepted | The SDK returned a quote successfully. | | onQuoteFailed | Quote request failed (network/validation/SDK error). | | onTransactionInitiated | User confirmed; the wallet was asked to sign/submit. | | onTransactionSettled | Transaction confirmed on-chain or settled by the backend. | | onTransactionFailed | Transaction reverted, was rejected, or failed before settling. | | onWalletConnected | An EVM or Solana wallet just connected. | | onWalletDisconnected | An EVM or Solana wallet just disconnected. | | onError | Any user-visible error surfaced (alongside the specific *_failed callback). | | onAnalyticsEvent | Every event above, in one stream (for analytics). |

Every event payload includes:

{
  id: string;          // nanoid, stable per event
  timestamp: number;   // Date.now() at emit
  flow?: 'swap' | 'onramp' | 'offramp';
  type: WidgetEventType;
  payload: { ... };    // discriminated by type
}

Analytics

onAnalyticsEvent receives every event in one stream, so you can forward them to an analytics sink in a single line instead of wiring all nine typed callbacks:

<Widget onAnalyticsEvent={(e) => analytics.track(e.type, e.payload)} />

Each event still fires its specific typed callback too, so you can run analytics off the firehose and product logic off the typed callbacks at the same time. The two are independent and each handler sees a given event once. Only if you route a typed callback and the firehose into the same effect do you need to guard against double-counting, keyed on event.id.

Payload redaction (PII)

Event payloads are deliberately redacted so they are safe to forward verbatim to a third-party analytics sink (Segment/GA/PostHog/Mixpanel):

• quote_accepted carries only a serializable summary — transactionId, provider, fromSymbol/toSymbol, fromAmount/toAmount, fromChainId/toChainId, estimatedDuration, and cached. It does not include deposit instructions (PIX key/QR, deposit address, reference id), the raw transactionRequest/approvalTxParams (signed calldata), or wallet addresses.
• quote_failed, transaction_failed, and error expose a human-readable message plus an optional causeMessage string. The underlying error object is never forwarded — viem/RPC errors embed transaction params and request payloads, so only a message string crosses the callback boundary.

If you need the full, unredacted quote (e.g. to render deposit instructions), read it from the hook return values (useOnRamp().quote, etc.) rather than from events.

SSR / RSC

@ordanetwork/widget is a client component. The bundle starts with 'use client'; so importing it from a React Server Component is safe — you'll get the 'use client' boundary automatically. You do not need to wrap it.

Config flags

| Field | Default | Effect | | --- | --- | --- | | disableOnRamp | false | Hide on-ramp (fiat → crypto) flows. | | disableOffRamp | false | Hide off-ramp (crypto → fiat) flows. |