> For the complete documentation index, see [llms.txt](https://docs.rujira.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rujira.network/developers/rujira-product-integration-guides/rujira-integration-kit.md).

# Rujira Integration Kit

Bring Rujira's products into your wallet or app. Your users stay in your interface and keep their own wallet connection. Rujira builds every transaction for you, and you can add an optional partner fee to earn on the volume you bring.

**Try it first:** the [Integration Kit playground](https://rujira-ui-main-git-feat-integration-kit-rujira.vercel.app/integrations) lets you test the widgets live. You can switch between dark and light themes and between React and web components, copy ready-made code for each widget, and see a fully custom UI built on the same hooks.

### What's in the kit

| Package           | Use it when                                 | What you get                                                                                                                                                                                                |
| ----------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@rujira/widgets` | You want Rujira working in your app quickly | Ready-made **Deposit**, **Borrow** and **Borrow Positions** widgets, as React components or framework-free web components. They're themeable and isolated in shadow DOM, so they won't clash with your CSS. |
| `@rujira/react`   | You want your own look and feel             | React hooks for markets, quotes, balances and transactions. You build the UI; the hooks do the rest.                                                                                                        |
| `@rujira/sdk`     | You use another framework, or no framework  | The TypeScript core under both: market data, quotes, transaction building, wallet adapters and partner fees.                                                                                                |

All three run on THORChain mainnet. Confirming a transaction moves real funds.

### Step-by-step

#### 1. Install the packages

```bash
npm install @rujira/sdk @rujira/widgets
# or, for a custom UI:
npm install @rujira/sdk @rujira/react
```

The React components and hooks need React 18 or 19. The web components need no framework.

#### 2. Get an API key (recommended)

The kit works without a key, but then you share a public rate limit with everyone else. For production, email [**api@rujira.network**](mailto:api@rujira.network) to request an API key, and pass it as `apiKey`.

In the same email, include the website(s) your integration runs on so we can whitelist them for the Rujira API. Browser requests from domains that aren't whitelisted are blocked, unless you route API calls through your own backend.

#### 3. Connect your wallet to Rujira (the "signer")

The kit never opens its own wallet popup. Your wallet stays in charge and you give the kit a **signer** that wraps it. Use the adapter that matches your setup:

| Your setup                                                                                  | Adapter                                               |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| cosmos-kit                                                                                  | `fromCosmosKit(useChain("thorchain"))`                |
| Any Cosmos offline signer (Keplr-style, or your own wallet)                                 | `fromOfflineSigner(getSigner, { address, walletId })` |
| EVM wallets (EIP-1193, MetaMask-style), for deposits from Ethereum, Base, BSC and Avalanche | `fromEip1193(() => provider, { walletId })`           |
| THORChain plus EVM in one wallet                                                            | `combineSigners(thorchainSigner, evmSigner)`          |

```ts
import { fromOfflineSigner, fromEip1193, combineSigners } from "@rujira/sdk";

// Your wallet's THORChain signer (chain id "thorchain-1")
const thorchain = fromOfflineSigner(
  () => myWallet.getOfflineSigner("thorchain-1"),
  { address: userThorAddress, walletId: "my-wallet" }
);

// Optional: let users fund deposits from EVM chains through the same wallet
const signer = combineSigners(thorchain, fromEip1193(() => myWallet.ethereum, { walletId: "my-wallet" }));
```

Pass `null` as the signer while no wallet is connected. The widgets then still show markets and quotes, and ask the user to connect when they need to.

> **Wallet teams:** borrowing needs a wallet that can sign THORChain contract executions (`MsgExecuteContract`). A signer built with `fromOfflineSigner` already declares that. Keplr, OKX, Vultisig and DAO DAO are tested and supported. EVM-only wallets can fund deposits, but can't borrow yet: that waits on THORChain adding EIP-712 signing.

#### 4. Integrate widgets or custom UIs

There  two ways to integrate Rujira into your application(s):

* **Widgets:** Use widgets with Rujira's UI styles to integrate fast
* **Custom UI**: Wrap your app once with the styles you have and then use the hooks wherever you need them

#### 4a. Drop in the widgets (fastest)

**React**

```tsx
import { RujiraDeposit, RujiraBorrow, RujiraBorrowPositions } from "@rujira/widgets";

<RujiraBorrow
  apiKey={apiKey}
  signer={signer}
  partnerFee={{ bps: 50, receiver: "thor1…your-fee-address" }}
  theme={{ mode: "dark" }}
  onConnectRequest={openYourConnectModal}
/>

<RujiraBorrowPositions apiKey={apiKey} signer={signer} onConnectRequest={openYourConnectModal} />

{/* Deposit as a modal that your own button opens. Leave `open` out to embed it inline instead. */}
<button onClick={() => setDepositOpen(true)}>Deposit to Rujira</button>
<RujiraDeposit
  apiKey={apiKey}
  signer={signer}
  open={depositOpen}
  onClose={() => setDepositOpen(false)}
  onConnectRequest={openYourConnectModal}
/>
```

**Web components (any framework, or plain HTML)**

```html
<rujira-borrow theme="dark"></rujira-borrow>

<script type="module">
  import { defineRujiraBorrow } from "@rujira/widgets";
  defineRujiraBorrow();

  const borrow = document.querySelector("rujira-borrow");
  borrow.config = { apiKey, partnerFee: { bps: 50, receiver: "thor1…" } };
  borrow.signer = signer; // or null while disconnected
  borrow.options = { onConnectRequest: openYourConnectModal };
  borrow.addEventListener("rujira-success", (e) => console.log(e.detail.txHash));
</script>
```

The available tags are `<rujira-deposit>`, `<rujira-borrow>` and `<rujira-borrow-positions>`. Each one fires `rujira-status`, `rujira-success` and `rujira-error`. The borrow and deposit widgets also fire `rujira-quote` when a quote updates, and the deposit modal fires `rujira-close`.

**Theming:** set `mode` to `"dark"` or `"light"`, and override individual colours and fonts with CSS tokens, for example `theme={{ mode: "light", tokens: { "--rj-accent": "#6E56CF" } }}`.

#### 4b. Or build your own UI with hooks

Wrap your app once, then use the hooks wherever you need them:

```tsx
import { RujiraProvider, useBorrowMarkets, useBorrowQuote, useBorrow } from "@rujira/react";

<RujiraProvider apiKey={apiKey} signer={signer} partnerFee={{ bps: 50, receiver: "thor1…" }}>
  <YourApp />
</RujiraProvider>
```

| Hooks                                                                                                      | For                                                              |
| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `useBorrowMarkets`, `useBorrowQuote`, `useBorrow`, `useBorrowAccount`, `useIncreaseQuote`, `useRepayQuote` | Borrow markets, quotes, and opening and managing positions       |
| `useDepositMarkets`, `useDepositQuote`, `useDeposit`, `useFundingBalances`                                 | Deposits into Rujira from any supported chain                    |
| `useBalances`, `useCapabilities`                                                                           | Wallet balances, and which products the connected wallet can use |

The Custom UI tab in the [playground](https://rujira-ui-main-git-feat-integration-kit-rujira.vercel.app/integrations) is built entirely from these hooks. Use it as a reference implementation.

#### 5. Earn with a partner fee (optional)

Add `partnerFee` to your config and you earn on the borrow positions your users open:

```ts
partnerFee: {
  bps: 50,                  // 0.5%: a whole number from 1 to 100
  receiver: "thor1…",       // your THORChain address
  basis: "borrowed",        // charged on the amount borrowed (default) or "collateral"
}
```

The fee is added to the transaction itself and rounds down in the user's favour. It currently applies to borrowing. The 100 bps maximum is provisional and may change before launch.

#### 6. Test and go live

1. Try your flows in the [playground](https://rujira-ui-main-git-feat-integration-kit-rujira.vercel.app/integrations) with a Keplr or Vultisig wallet.
2. Integrate in your app with a small amount first. It's mainnet, so transactions are real.
3. Before launch, make sure your API key is set and your website is whitelisted, as in step 2.
4. Tell us when you're live, and we'll help announce your integration.

### Need help?

Email [**api@rujira.network**](mailto:api@rujira.network). We can help with API keys, website whitelisting, wallet support and anything else you need to ship.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rujira.network/developers/rujira-product-integration-guides/rujira-integration-kit.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
