# Widget (beta)

## Introduction

The orda widget is a comprehensive, embeddable React component that enables multi-chain cryptocurrency payments in your application. Built on top of the `@ordanetwork/sdk`, it provides a complete payment solution with minimal configuration.

{% hint style="info" %}
Try the [widget →](https://widget.orda.network/)
{% endhint %}

### Key Features

* **Multi-Chain Support**: EVM chains (Ethereum, Polygon, Arbitrum, Base, Optimism, etc.) and Solana
* **Multiple Transaction Types**:
  * **Swap**: Cross-chain token swaps
  * **Off-Ramp**: Convert crypto to fiat (crypto → BRL via PIX)
  * **On-Ramp**: Convert fiat to crypto (BRL → crypto via PIX)
* **Wallet Integration**: Seamless connection with WalletConnect/Reown AppKit
* **Recipient Management**: Save and manage payment recipients
* **Token Prices & Balances**: Real-time USD prices and multi-chain balance fetching
* **Responsive Design**: Works on desktop and mobile devices
* **Customizable Theming**: CSS variables for easy customization

### Prerequisites

Before integrating the widget, you'll need:

1. **WalletConnect Project ID**: Create a free project at <https://cloud.reown.com/>
2. **orda API Credentials**: Sign up at the orda developer portal to get your `clientId` and `clientSecret`
3. **React Application**: The widget requires React 18+ or React 19+
4. **Node.js**: Version 18 or higher

***

## Installation

Install the SDK and required peer dependencies.

{% tabs %}
{% tab title="npm" %}

```bash
npm install @ordanetwork/sdk \
  react react-dom \
  wagmi viem \
  @tanstack/react-query \
  @solana/web3.js
```

{% endtab %}

{% tab title="yarn" %}

```bash
yarn add @ordanetwork/sdk \
  react react-dom \
  wagmi viem \
  @tanstack/react-query \
  @solana/web3.js
```

{% endtab %}

{% tab title="pnpm" %}

```bash
pnpm add @ordanetwork/sdk \
  react react-dom \
  wagmi viem \
  @tanstack/react-query \
  @solana/web3.js
```

{% endtab %}
{% endtabs %}

### Version Compatibility

| Package                 | Version              |
| ----------------------- | -------------------- |
| `@ordanetwork/sdk`      | Latest               |
| `react`                 | ^18.0.0 \|\| ^19.0.0 |
| `react-dom`             | ^18.0.0 \|\| ^19.0.0 |
| `wagmi`                 | ^2.0.0               |
| `viem`                  | ^2.0.0               |
| `@tanstack/react-query` | ^5.0.0               |
| `@solana/web3.js`       | ^1.90.0              |

***

## Quick Start

This section shows you how to integrate the widget in a Next.js App Router application (the recommended approach). See other examples for Vite, Create React App and Next.js Pages router [here](https://docs.orda.network/developers/widget-beta/frameworks).

{% stepper %}
{% step %}

### Set Environment Variables

Create a `.env.local` file in your project root:

```bash
# WalletConnect / Reown Project ID

# Get yours at: https://cloud.reown.com/
NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=your_walletconnect_project_id

# orda API Credentials (server-side only)
ORDA_CLIENT_ID=prj_your_client_id
ORDA_CLIENT_SECRET=sec_your_client_secret

# NEXT_PUBLIC_ORDA_API_BASE_URL=https://api.orda.network/v1
```

{% hint style="warning" %}
Security Note: Never expose `ORDA_CLIENT_SECRET` to the browser. Use server-side routes for authentication.
{% endhint %}
{% endstep %}

{% step %}

### Create JWT Authentication Route

Create a server-side API route to exchange your credentials for a JWT token.

File: `app/api/auth/jwt/route.ts`

{% code title="app/api/auth/jwt/route.ts" %}

```typescript
import { NextResponse } from 'next/server';
import { UniversalHttpClient, JWT } from '@ordanetwork/sdk';

const CLIENT_ID = process.env.ORDA_CLIENT_ID!;
const CLIENT_SECRET = process.env.ORDA_CLIENT_SECRET!;
const API_URL = process.env.NEXT_PUBLIC_ORDA_API_BASE_URL || 'https://api.orda.network/v1';

export async function POST() {
  try {
    // Validate credentials are configured
    if (!CLIENT_ID || !CLIENT_SECRET) {
      console.error('Missing ORDA_CLIENT_ID or ORDA_CLIENT_SECRET');
      return NextResponse.json(
        { error: 'Server configuration error: missing API credentials' },
        { status: 500 }
      );
    }

    // Create HTTP client and JWT API
    const httpClient = new UniversalHttpClient(API_URL, 30000);
    const jwtApi = new JWT(httpClient);

    // Generate JWT with required permissions
    const { token, expiresAt } = await jwtApi.generate({
      clientId: CLIENT_ID,
      clientSecret: CLIENT_SECRET,
      permissions: [
        'quotes:read',
        'offramp:read',
        'onramp:read',
        'transactions:read',
        'recipients:read',
        'recipients:write',
        'balances:read',
        'prices:read'
      ],
    });

    // Return token in expected format
    return NextResponse.json({
      jwt: token,
      expiresAt: Math.floor(new Date(expiresAt).getTime() / 1000),
    });
  } catch (error: any) {
    console.error('Token generation error:', error);
    return NextResponse.json(
      { error: error?.message || 'Failed to generate token' },
      { status: error?.statusCode || 500 }
    );
  }
}
```

{% endcode %}
{% endstep %}

{% step %}

### Create Provider Component

Create a client component that wraps your app with the orda provider.

File: `app/providers.tsx`

{% code title="app/providers.tsx" %}

```typescript
'use client';

import { OrdaProvider, createAppKitConfig } from '@ordanetwork/sdk/react';

// Create AppKit config at module level (required for SSR compatibility)
const appKitConfig = createAppKitConfig({
  projectId: process.env.NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID!,
  metadata: {
    name: 'Your App Name',
    description: 'Your app description',
    url: 'https://yourapp.com',
    icons: ['https://yourapp.com/icon.png'],
  },
});

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <OrdaProvider
      config={{
        // Fetch JWT from your server route
        getToken: async () => {
          const res = await fetch('/api/auth/jwt', { method: 'POST' });
          if (!res.ok) {
            const error = await res.json();
            throw new Error(error.error || 'Failed to get JWT token');
          }
          return res.json(); // Returns { jwt, expiresAt }
        },
        appKitConfig,
        debug: process.env.NODE_ENV === 'development', // Enable debug logs in dev
      }}
    >
      {children}
    </OrdaProvider>
  );
}
```

{% endcode %}
{% endstep %}

{% step %}

### Update Root Layout

Import the widget styles and wrap your app with the Providers component.

File: `app/layout.tsx`

{% code title="app/layout.tsx" %}

```typescript
import type { Metadata } from 'next';
import './globals.css';
import '@ordanetwork/sdk/react/styles.css'; // Import widget styles
import { Providers } from './providers';

export const metadata: Metadata = {
  title: 'Your App',
  description: 'Your app with orda payment widget',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

{% endcode %}
{% endstep %}

{% step %}

### Use the Widget

Import and render the widget in your page.

File: `app/page.tsx`

{% code title="app/page.tsx" %}

```typescript
'use client';

import { Widget } from '@ordanetwork/sdk/react';

export default function Home() {
  return (
    <main className="min-h-screen flex items-center justify-center p-4 bg-zinc-100">
      <div className="w-full max-w-md">
        <h1 className="text-2xl font-bold text-center mb-6">
          Crypto Payments
        </h1>
        <Widget />
      </div>
    </main>
  );
}
```

{% endcode %}
{% endstep %}

{% step %}

### Run Your App

```bash
npm run dev
```

Visit `http://localhost:3000` and you should see the orda payment widget!
{% endstep %}
{% endstepper %}