# Wallet Integration Guide

## Overview

The BRIJ Widget SDK allows wallets and dApps to embed crypto on/off-ramp functionality directly into their applications.
With just a few lines of code, you can provide your users with seamless fiat-to-crypto and crypto-to-fiat conversion
powered by BRIJ's network of ramp partners.

## Features

* **Easy Integration**: Add on/off-ramp functionality with minimal code
* **Customizable UI**: Match the widget appearance to your application's design
* **Multi-Chain Support**: Support for all major blockchain [networks](/docs/reference/networks)
* **Flexible Modes**: Enable on-ramp, off-ramp, or both

## Getting Started

1. **Contact BRIJ** to obtain your API key
2. **Add the SDK** to your application using CDN or npm
3. **Initialize the widget** with your API key and desired configuration
4. **Customize the theme** to match your application's design (optional)

## Installation

### 1. Add the SDK

#### CDN

Add the SDK script to your HTML:

```html
<script src="https://unpkg.com/@brij-fi/widget-sdk/dist/index.umd.js"></script>
```

#### npm

Install via npm:

```bash
npm install @brij-fi/widget-sdk
```

### 2. Initialize the Widget

Create a container element and initialize the SDK:

```html

<div id="brij-widget"></div>

<script>
    const {BrijSDK, BrijAction} = window.BrijSDK;

    const sdk = BrijSDK.init('#brij-widget', {
        apiKey: 'your-api-key',
    });
</script>
```

That's it! The widget is now ready to use.

## Configuration Options

### Basic Configuration

| Option            | Type       | Required | Description                                                                                                                   |
| ----------------- | ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`          | `string`   | Yes      | Your BRIJ API key                                                                                                             |
| `chains`          | `string[]` | No       | Array of [network codes](/docs/reference/networks) to support (omit for all chains)                                           |
| `mode`            | `string[]` | No       | Array of modes: `'ONRAMP'`, `'OFFRAMP'`, or both (omit to support both)                                                       |
| `country`         | `string`   | No       | Customer's country code (ISO 3166-1 alpha-3), e.g., `'USA'`. Preselected in the widget and passed to partners that support it |
| `walletAddresses` | `object`   | No       | Wallet addresses mapped by chain, e.g., `{ SOLANA: 'abc...', ETHEREUM: '0x...' }`. Passed to partners that support it         |
| `theme`           | `object`   | No       | Theme customization options (see [below](#theme-customization))                                                               |

### Example with Options

```javascript
const sdk = BrijSDK.init('#brij-widget', {
    apiKey: 'your-api-key',
    chains: ['SOLANA', 'ETHEREUM', 'BASE'],
    mode: ['ONRAMP'],
});
```

## Theme Customization

The widget supports two predefined themes (`light` and `dark`) with full color customization. Select a base theme with
`mode`, then override specific colors as needed.

### Built-in Themes

|                           Light                           |                           Dark                           |
| :-------------------------------------------------------: | :------------------------------------------------------: |
| ![Light theme](https://files.buildwithfern.com/brij.docs.buildwithfern.com/12990ae33210fbd9bcae08fefebc4b55dc16f4680571c73ce077d62c86db5dd9/docs/assets/wallets/light.png) | ![Dark theme](https://files.buildwithfern.com/brij.docs.buildwithfern.com/bd94e2a588fd738a3192fb06f7707f7f19d8b50336d25f1b685766ce93dc6d8b/docs/assets/wallets/dark.png) |

```javascript
const sdk = BrijSDK.init('#brij-widget', {
    apiKey: 'your-api-key',
    theme: {
        mode: 'dark',
        logoUrl: 'https://your-site.com/logo.png',
        primaryBrand: 'FF4500',
        primaryCtaBgActive: '2563EB',
    }
});
```

### Theme Options

#### General

| Option    | Type     | Default                                                     | Description                                                                               |
| --------- | -------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `logoUrl` | `string` | `https://widget.brij.fi/assets/assets/images/brij_logo.svg` | URL to your logo image (PNG, JPG, or SVG). Displays at 31px height with auto-scaled width |
| `mode`    | `string` | `'light'`                                                   | Base theme: `'light'` or `'dark'`. Partner colors override on top                         |

#### Backgrounds

| Option         | Type     | Description                                   |
| -------------- | -------- | --------------------------------------------- |
| `contentBg`    | `string` | Main content area and modal/drawer background |
| `pageBg`       | `string` | Page background (lower content area)          |
| `inputFieldBg` | `string` | Background color for text input fields        |

#### Text

| Option       | Type     | Description                  |
| ------------ | -------- | ---------------------------- |
| `text`       | `string` | Primary text color           |
| `footerText` | `string` | Footer/disclaimer text color |

#### Brand

| Option         | Type     | Description                                              |
| -------------- | -------- | -------------------------------------------------------- |
| `primaryBrand` | `string` | Primary brand color for accent elements and glow effects |

#### Primary CTA Buttons

| Option                   | Type     | Description                       |
| ------------------------ | -------- | --------------------------------- |
| `primaryCtaBgActive`     | `string` | Background color (active state)   |
| `primaryCtaBgInactive`   | `string` | Background color (disabled state) |
| `primaryCtaTextActive`   | `string` | Text color (active state)         |
| `primaryCtaTextInactive` | `string` | Text color (disabled state)       |

#### Secondary CTA Buttons

| Option             | Type     | Description      |
| ------------------ | -------- | ---------------- |
| `secondaryCtaBg`   | `string` | Background color |
| `secondaryCtaText` | `string` | Text color       |

#### Menu

| Option       | Type     | Description                 |
| ------------ | -------- | --------------------------- |
| `menuButton` | `string` | Menu button icon/text color |

**Note:** Color values should be provided as hex codes **without** the `#` prefix (e.g., `'FF4500'` for orange, `'FF000080'` for 50% transparent red).

## Examples

### On-Ramp Only (Solana)

Enable only fiat-to-crypto conversion on Solana:

```javascript
const sdk = BrijSDK.init('#brij-widget', {
    apiKey: 'your-api-key',
    chains: ['SOLANA'],
    mode: ['ONRAMP'],
});
```

### Off-Ramp Only (Multiple Chains)

Enable only crypto-to-fiat conversion on Ethereum and Base:

```javascript
const sdk = BrijSDK.init('#brij-widget', {
    apiKey: 'your-api-key',
    chains: ['ETHEREUM', 'BASE'],
    mode: ['OFFRAMP'],
});
```

### Full Configuration with Custom Theme

```javascript
const sdk = BrijSDK.init('#brij-widget', {
    apiKey: 'your-api-key',
    chains: ['SOLANA', 'ETHEREUM', 'BASE', 'POLYGON'],
    mode: ['ONRAMP', 'OFFRAMP'],
    theme: {
        mode: 'dark',
        logoUrl: 'https://your-site.com/logo.png',
        primaryBrand: '6366F1',
        contentBg: '0F0F23',
        primaryCtaBgActive: '4F46E5',
    }
});
```

## Supported Networks

The widget supports all BRIJ [networks](/docs/reference/networks). Use the network codes when configuring
the `chains` option:

* `SOLANA` - Solana
* `ETHEREUM` - Ethereum
* `BASE` - Base
* `POLYGON` - Polygon
* `ARBITRUM` - Arbitrum
* `OPTIMISM` - Optimism
* `BSC` - BNB Smart Chain
* `AVALANCHEC` - Avalanche C-Chain
* `BITCOIN` - Bitcoin
* `TON` - TON
* `TRON` - TRON