Embed NLO in three steps

What is Ultra-Safe?

Ultra-Safe is the NLO strategy your users deposit into through the widget. NLO handles opportunity scanning, routing, execution, and rebalancing automatically — so you can embed managed DeFi yield without building the infrastructure yourself.

1. Install SDK

The SDK is published as an npm package — works in React, Vue, Next.js, Angular, Svelte, and vanilla JS bundlers. Requires Node 18+.

npm install @nlofinance/widget

On a fresh install (no existing .nlowidget.json in the project root) the package prints a one-line banner reminding you to run the signup wizard:

👋 Welcome to the NLO partner widget.
   Run this to set up your partner account:

     npx nlo-init

The banner is suppressed on subsequent installs (when .nlowidget.json exists) and on non-interactive installs (npm ci, Docker, CI).

Once installed and your partner slug is created, jump to 3. Render the widget for copy-paste-ready React or Vue components.

2. Create partner slug

npx nlo-init is an interactive wizard shipped with the SDK. Run it once per project, in a real terminal:

npx nlo-init

What it prompts for

Wizard output

$ npx nlo-init

[NLO Widget] 👋 Welcome. Let's set up your NLO partner account.

? Company name: … Your Company
? Production domain (https://...): … https://example.com
? Payout wallet (0x... 42 chars): … 0x0000000000000000000000000000000000000000
? Contact email: … you@example.com

[NLO Widget] Submitting signup to https://nlo.finance …
[NLO Widget] ✓ Done! Your partner slug: your-company
[NLO Widget] ✓ Saved to .nlowidget.json (safe to commit — slug is public).

[NLO Widget] Use it in your code:

    import NLOWidget from "@nlofinance/widget";
    NLOWidget.mount("#nlo-widget", {
      partner: "your-company",
      title: "Your Company",
    });

What gets written: .nlowidget.json

{
  "slug": "your-company",
  "company_name": "Your Company",
  "website_url": "https://example.com",
  "payout_wallet": "0x0000000000000000000000000000000000000000",
  "contact_email": "you@example.com",
  "signed_up_at": "2026-05-28T10:14:31.000Z",
  "source": "self-service"
}

Commit this file to git. The slug is public — it's in your bundle anyway when you mount the widget. Committing it means every developer / CI run uses the same slug without having to re-register.

Safe to re-run

• Existing config. If .nlowidget.json already exists and has a slug, the wizard exits with "Already configured" — no prompts, no API call.
• Same domain, different machine. If your domain is already registered (e.g. a coworker ran the wizard first), the backend returns the existing slug and the wizard saves it automatically. Same slug for every dev on the team — no duplicate rows.
• Non-interactive context. CI / Docker / piped stdin / npm ci all skip the wizard silently. Run npx nlo-init manually in a real terminal once (commit the result), then CI will use the committed config.

3. Render the widget

Drop one of these components into your project. The slug comes from .nlowidget.json (written by npx nlo-init) so partners never hard-code it.

The widget auto-sizes its own iframe (SDK v1.0.0+) — you don't need to wire onResize or track height in component state. Just mount it.

import { useEffect, useRef } from "react";
import NLOWidget from "@nlofinance/widget";
import config from "../.nlowidget.json";   // adjust path to your project root

export default function NLODeposit() {
  const hostRef = useRef(null);

  useEffect(() => {
    const handle = NLOWidget.mount(hostRef.current, {
      partner: config.slug,
      title: config.company_name,
    });
    return () => handle.unmount();
  }, []);

  return <div ref={hostRef} style={{ width: 480, maxWidth: "100%" }} />;
}

import NLODeposit from "./components/NLODeposit";

export default function App() {
  return (
    <main>
      <h1>Deposit into NLO Ultra-Safe</h1>
      <NLODeposit />
    </main>
  );
}

<script setup>
import { onBeforeUnmount, onMounted, ref } from "vue";
import NLOWidget from "@nlofinance/widget";
import config from "../../.nlowidget.json";   // adjust path to your project root

const hostEl = ref(null);
let handle = null;

onMounted(() => {
  handle = NLOWidget.mount(hostEl.value, {
    partner: config.slug,
    title: config.company_name,
  });
});

onBeforeUnmount(() => {
  if (handle) handle.unmount();
});
</script>

<template>
  <div ref="hostEl" style="width: 480px; max-width: 100%"></div>
</template>

<script setup>
import NLODeposit from "./components/NLODeposit.vue";
</script>

<template>
  <main>
    <h1>Deposit into NLO Ultra-Safe</h1>
    <NLODeposit />
  </main>
</template>

<div id="nlo-widget" style="width: 480px; max-width: 100%"></div>

<script type="module">
  import NLOWidget from "https://cdn.jsdelivr.net/npm/@nlofinance/widget@1/dist/index.esm.js";

  // Inline the slug from .nlowidget.json — for plain HTML you can't
  // import JSON natively, so paste the value:
  const SLUG = "your-slug-from-nlowidget-json";

  NLOWidget.mount("#nlo-widget", {
    partner: SLUG,
    title: "Your App",
  });
</script>

Mount options

NLOWidget.mount(target, options) mounts the hosted iframe inside the target element and returns a handle. Call handle.unmount() to clean up when your framework component unmounts.

Options

Connect Wallet & Deposit Flow

Here's what the user sees end-to-end. The widget handles wallet connection (Reown AppKit — MetaMask, WalletConnect, Coinbase Wallet), chain switching, ERC-20 approval, and the deposit transaction. Your page does not need to listen for events unless you want custom analytics, quest logic, or post-deposit UI.

Step-by-step

1. Connect wallet. Tap Connect wallet → Reown AppKit modal opens with MetaMask, WalletConnect QR, Coinbase Wallet, etc. The widget binds the connected wallet to your partner account (Tier 2 attribution) automatically.
2. Pick an asset. The widget shows live balances for every supported (token, chain) combo. User picks an asset and types an amount.
3. Approve + Deposit. One tap. The widget handles chain switching, the ERC-20 approve transaction (if not already approved), and the deposit transaction in sequence. The user signs in their wallet; the widget polls for confirmations and records the deposit on NLO's backend.
4. Success. The widget shows a success screen with the on-chain tx hash. If you wired optional events, onDepositComplete also gives you { tx_hash, chain, token_symbol, amount_display, amount_raw, deposit_uuid, wallet }.

Optional events

You do not need events for a basic embed. Use them only if your app wants to update UI, send analytics, advance a quest, or run custom post-deposit logic. For a TaskOn-style placement, you can skip this section entirely.

NLOWidget.mount("#nlo-widget", {
  partner: "your-slug",
  title: "Your App",

  onDepositComplete: (e) => {
    // Optional: use the real on-chain tx hash for your own UX or analytics.
    console.log("deposit complete:", e.tx_hash);
  },

  onDepositFailed: (e) => {
    // Optional: capture this for debugging or support.
    console.warn("deposit failed at", e.step, "-", e.message);
  },
});

Set the display title

The V1 widget keeps customization intentionally small. Partners can set a display title for the header above VIA NLO. Deeper visual customization is handled by NLO during partner onboarding so the deposit flow stays readable, compliant, and easy to support.

NLOWidget.mount("#nlo-widget", {
  partner: "your-slug",
  title: "Your App",
});