@aurora-is-near/intents-swap-widget

A React cross-chain swap widget powered by NEAR Intents. Drop it into your app and let users swap any supported asset across 35+ chains from a single UI, while you earn fees on every swap.

[!TIP] Just need a working widget with wallet connection built in? Use @aurora-is-near/intents-swap-widget-standalone. This package (the core) is for apps that already connect wallets and want full control.

Contents

• At a glance
• Widget Studio
• Choose your integration
• Quick start
• How it works
• Wallets and chain adapters
• Configuration
• Widgets and events
• Theming and localisation
• Subpath exports (build your own UI)
• Troubleshooting
• Documentation map

At a glance

Widget Studio

Widget Studio is a no-code dashboard for the widget. Use it to:

• 🔑 Get your API key. It is required, and it is also where your fees are configured.
• 🌐 Pick networks and tokens, set default sell/buy tokens, and choose confidentiality mode.
• 🎨 Design it: Clean or Bold style, accent and background colours, corner radius, container.
• 👀 Preview it live before shipping.
• 📦 Embed it: Embed in your app gives you an iframe link or a ready-to-paste React snippet.
• 📊 Download reports of swaps made with your API keys (CSV).

[!NOTE] The API key is not secret. It is safe to ship in front-end code.

Choose your integration

flowchart TD
    A[I want a swap widget in my app] --> B{Need code-level control?}
    B -- No --> IF["<b>iframe</b><br/>Copy the link from Widget Studio"]
    B -- Yes --> C{Does your app already<br/>connect wallets?}
    C -- No --> SA["<b>@aurora-is-near/intents-swap-widget-standalone</b><br/>Wallet modal built in"]
    C -- Yes --> CORE["<b>@aurora-is-near/intents-swap-widget</b><br/>+ chain adapters you need"]

Quick start

1. Install the core package and the adapter for each chain family your wallets support:

npm install @aurora-is-near/intents-swap-widget
# Add only what you need:
npm install @aurora-is-near/intents-swap-widget-evm      # Ethereum, Base, Arbitrum, …
npm install @aurora-is-near/intents-swap-widget-solana   # Solana
npm install @aurora-is-near/intents-swap-widget-stellar  # Stellar

2. Render the widget inside WidgetConfigProvider:

import '@aurora-is-near/intents-swap-widget/styles.css';

import {
  Widget,
  WidgetConfigProvider,
} from '@aurora-is-near/intents-swap-widget';
import { evm } from '@aurora-is-near/intents-swap-widget-evm';

export function Swap() {
  const { address, connect, disconnect } = useYourEvmWallet(); // your wallet lib

  return (
    <WidgetConfigProvider
      config={{
        apiKey: 'YOUR_STUDIO_API_KEY',
        connectedWallets: { default: address },
        providers: { evm: window.ethereum }, // any EIP-1193 provider
        plugins: { evm },
        onWalletSignin: connect,
        onWalletSignout: disconnect,
      }}
      theme={{ colorScheme: 'dark', accentColor: '#bc9cf8' }}>
      <Widget />
    </WidgetConfigProvider>
  );
}

That's a working swap widget. Next: add more chains, restrict tokens, or match your brand.

How it works

The widget never holds user funds. Each swap is a quote → deposit → settle flow:

sequenceDiagram
    autonumber
    actor U as User
    participant W as Swap Widget
    participant API as Aurora Intents API
    participant P as Chain adapter + wallet
    participant NI as NEAR Intents

    U->>W: Pick tokens and amount
    W->>API: Request quote (apiKey, fees, slippage)
    API-->>W: Quote + one-time deposit address
    U->>W: Click "Swap"
    W->>P: makeTransfer(amount → deposit address)
    P-->>W: Transaction hash (user signs in wallet)
    NI->>NI: Solvers fill the intent
    W->>API: Poll swap status
    API-->>W: Success, funds sent to recipient

The chain adapter (plugins.evm, plugins.sol, …) only handles step 5: sending funds from the user's wallet to the deposit address on the source chain. The rest is shared by all chains.

Wallets and chain adapters

The core package does not bundle chain SDKs. You pass three things for each chain family:

Any supported chain can be a destination, whether or not the user has a wallet for it. With allowSwapWithExternalWallet, users can also deposit from any chain by sending to a QR-code address.

import { evm } from '@aurora-is-near/intents-swap-widget-evm';
import { sol } from '@aurora-is-near/intents-swap-widget-solana';
import { stellar } from '@aurora-is-near/intents-swap-widget-stellar';

const config = {
  apiKey: 'YOUR_STUDIO_API_KEY',
  connectedWallets: {
    default: evmAddress,
    sol: solanaAddress,
    stellar: stellarAddress,
    near: nearAccountId,
    ton: tonAddress,
  },
  providers: {
    evm: window.ethereum,
    sol: { publicKey, signMessage, signTransaction },
    stellar: { publicKey: stellarAddress, signMessage, signTransaction },
    near: () => nearWallet,
  },
  plugins: { evm, sol, stellar },
  onWalletSignin: openWalletModal,
  onWalletSignout: disconnect,
};

Adapter guides for Privy, NEAR and TON: 📖 Wallet Connection docs.

Configuration

Everything goes through the config prop of WidgetConfigProvider. Other props: theme, localisation, rpcs, balanceViaRpc. These are the options most integrations use:

<WidgetConfigProvider
  config={{
    apiKey: 'YOUR_STUDIO_API_KEY',
    allowedChainsList: ['eth', 'base', 'arb', 'sol', 'near'],
    allowedTokensList: ['USDC', 'USDT', 'ETH', 'SOL'],
    appFees: [{ recipient: 'your-app.near', fee: 20 }], // 0.2%
    slippageTolerance: 50, // 0.5%
  }}>
  <Widget />
</WidgetConfigProvider>

📖 Full reference (40+ options): Widget Configuration docs. An in-repo copy lives at docs/configuration.md, and the WidgetConfig type is in src/types/config.ts. yarn check-docs keeps the doc and the type in sync.

Widgets and events

Events: listen to the transfer pipeline with onMsg:

<Widget
  onMsg={(msg) => {
    if (msg.type === 'on_transfer_success') {
      analytics.track('swap', { hash: msg.hash });
    }
  }}
/>

Custom transfers: send the deposit yourself (e.g. for TON) and return the hash:

<Widget
  makeTransfer={async (args) => {
    const hash = await sendTon(args.address, args.amount);
    return { hash, transactionLink: `https://tonviewer.com/transaction/${hash}` };
  }}
/>

📖 Widgets docs

Theming and localisation

[!IMPORTANT] Always import @aurora-is-near/intents-swap-widget/styles.css. If your app has a global CSS reset, wrap it in @layer base { … }, otherwise Tailwind layering removes the widget's spacing.

Subpath exports (build your own UI)

Use the pieces directly if the pre-built widgets don't fit your use case:

Troubleshooting

📖 Troubleshooting docs · Open an issue

Documentation map

License

MIT