💻Widget

Easily integrate Panora’s swap functionality into your application with our lightweight SDK, enabling seamless token swaps and real-time data directly within your platform.

Key Features

Quick Setup: Simple, plug-and-play integration.
Customizable: Adapt to match your app’s style.
Comprehensive Swap Support: Includes wallet connections, token swaps, and optimized routes.
Real-Time Rates: Access the best swap prices instantly.

Getting Started

Public API Key:
```
a4^KV_EaTf4MW#ZdvgGKX#HUD^3IFEAOV_kzpIE^3BQGA8pDnrkT7JcIy#HNlLGi
```
Note: This API key's limits should be sufficient for most use cases. Protocols within the Aptos ecosystem with specific requirements or customization may submit a ticket on Discord.

How to Use

1. Installation

a. Setup via HTML

<!-- Load the Panora Widget script in your <head> -->
<script src="https://app.panora.exchange/widget-v1.js"></script>

<!-- Prepare a container in your <body> for the Panora Widget -->
<!-- Adjust width and height to suit your layout -->
<div id="panora-widget" style="width: 400px; height: 568px"></div>

Usage

<!-- Initialize the widget in your <body> after the container -->
<script>
  window.Panora.init({
    integratedTargetId: "target-container",
    panoraApiKey: "PANORA_API_KEY", // Optional. Default is Panora's public api key
    geomiApiKey: "GEOMI_API_KEY", // Optional. Takes higher priority over rpcUrl
    rpcUrl: "CUSTOM_RPC_URL", // Optional
  });
</script>

b. Alternatively, Install From NPM

Using npm

npm install @panoraexchange/widget-sdk

Using yarn

yarn add @panoraexchange/widget-sdk

Using pnpm

pnpm add @panoraexchange/widget-sdk

Usage

Integrate Panora Swap Widget into your application:

import { PanoraWidget, PanoraWidgetConfig } from "@panoraexchange/widget-sdk"

const widgetConfig: PanoraWidgetConfig = {
  panoraApiKey: "PANORA_API_KEY", // Optional. Default is Panora's public api key
  geomiApiKey: "GEOMI_API_KEY", // Optional. Takes higher priority over rpcUrl
  rpcUrl: "CUSTOM_RPC_URL", // Optional
}

export const Page = () => {
  return <PanoraWidget config={widgetConfig} />;
}

Compatibility

Create-React-App (React 18) (Example)
Next.js (Example)

2. Configurations

Widet Configurations

import { PanoraWidget, PanoraWidgetConfig } from "@panoraexchange/widget-sdk"

const widgetConfig: PanoraWidgetConfig = {
  /**
   * The Ed25519 account object to use for transactions. 
   * If not provided, the widget will rely on wallet connections.
   */
  account?: Ed25519Account

  /**
   * API key for Panora services. 
   * Defaults to Panora's public API key if not specified.
   */
  panoraApiKey?: string

  /**
   * API key for Geomi services. 
   * Takes higher priority over `rpcUrl` if both are provided.
   */
  geomiApiKey?: string

  /**
   * Custom RPC URL for blockchain interactions. 
   * Used only if `geomiApiKey` is not specified.
   */
  rpcUrl?: string

  /**
   * Whether to show the "Connect Wallet" button inside the widget.
   * Default: true
   */
  independentWalletConnection: boolean

  /**
   * Whether to show detailed information about the swap transaction.
   * Default: true
   */
  showRouteInfo?: boolean

  /**
   * Override the list of enabled wallets that appear in the widget.
   */
  enabledWallets?: WALLET[]

  /**
   * Whether to display "Powered by" credits in the widget.
   */
  showCredits?: boolean

  /**
   * Display mode of the widget:
   * - "MODAL": Opens as a popup modal
   * - "INTEGRATED": Fully embedded in the page
   * - "WIDGET": Floating widget mode
   */
  displayMode: "MODAL" | "INTEGRATED" | "WIDGET"

  /**
   * Default list of favorite tokens (by address) 
   * to be shown in the token picker.
   */
  defaultFavoriteTokens?: `0x${string}`[]

  /**
   * Transaction configuration parameters. 
   * Sensible defaults are applied if not provided.
   */
  transactionOptions?: {
    /**
     * Maximum gas limit for the transaction.
     */
    maxGasAmount?: number

    /**
     * Price per unit of gas (in smallest denomination).
     */
    gasUnitPrice?: number

    /**
     * Unix timestamp after which the transaction will expire 
     * if not included in the blockchain.
     */
    expireTimestamp: number
  }

  /**
   * Custom styles for theming the widget UI.
   */
  styles?: {
    primary?: string
    bgPrimary?: string
    borderPrimary?: string
    borderSecondary?: string
    shadowPrimary?: string
    btnTextPrimary?: string
    btnTextSecondary?: string
    textSecondary?: string
    warning?: string
    error?: string
    textPrimary?: string
    skeletonBase?: string
    skeletonHighlight?: string
    bgError?: string
    bgSuccess?: string
    bgSecondary?: string
    width?: string
  }

  /**
   * Size of the widget button when in floating widget mode.
   * - "SMALL"
   * - "DEFAULT"
   */
  widgetBtnSize?: "SMALL" | "DEFAULT"

  /**
   * Position of the widget button when in floating widget mode.
   */
  widgetBtnDirection?: "left-top" | "left-bottom" | "right-top" | "right-bottom"

  /**
   * Offset (in px) for the floating widget button’s position.
   */
  widgetBtnOffset?: {
    x: number
    y: number
  }

  /**
   * Default slippage percentage used in swaps 
   * if not overridden by the user.
   */
  defaultSlippagePercentage?: number

  /**
   * Default "from" token address for swaps.
   */
  defaultFromTokenAddress?: `0x${string}`

  /**
   * Default "to" token address for swaps.
   */
  defaultToTokenAddress?: `0x${string}`

  /**
   * Wallet address of the integrator (project) to receive fees.
   */
  integratorWalletAddress?: `0x${string}`

  /**
   * Percentage fee taken by the integrator on each swap.
   */
  integratorFeePercentage?: number
}

Theme Customizations

import { PanoraWidget } from "@panoraexchange/widget-sdk"

// Using Html Script
<script>
  window.Panora.init({
    integratedTargetId: "target-container",
    styles: {
      primary: "#5fdfac",
      bgPrimary: "#010D09",
      borderPrimary: "rgba(255, 255, 255, .05)",
      borderSecondary: "rgb(95 223 172 / 0.05)",
      shadowPrimary:
        "rgb(0 0 0 / 16%) 0px 2px 4px, rgb(0 0 0 / 32%) 0px 8px 16px",
      btnTextPrimary: "black",
      btnTextSecondary: "rgba(0, 0, 0, .25)",
      textSecondary: "rgb(107 114 128)",
      warning: "#EF8E19",
      error: "#F6465D",
      textPrimary: "white",
      skeletonBase: "rgb(255,255,255, .05)",
      skeletonHighlight: "rgb(255,255,255, .1)",
      bgError: "rgb(246, 70, 93, .1)",
      bgSuccess: "rgb(95, 223, 172, .1)",
      bgSecondary: "#000704",
    },
  });
</script>

// Using Npm package
const App = () => (
  <PanoraWidget
    config={{
      styles: {
        primary: "#5fdfac",
        bgPrimary: "#010D09",
        borderPrimary: "rgba(255, 255, 255, .05)",
        borderSecondary: "rgb(95 223 172 / 0.05)",
        shadowPrimary:
          "rgb(0 0 0 / 16%) 0px 2px 4px, rgb(0 0 0 / 32%) 0px 8px 16px",
        btnTextPrimary: "black",
        btnTextSecondary: "rgba(0, 0, 0, .25)",
        textSecondary: "rgb(107 114 128)",
        warning: "#EF8E19",
        error: "#F6465D",
        textPrimary: "white",
        skeletonBase: "rgb(255,255,255, .05)",
        skeletonHighlight: "rgb(255,255,255, .1)",
        bgError: "rgb(246, 70, 93, .1)",
        bgSuccess: "rgb(95, 223, 172, .1)",
        bgSecondary: "#000704",
      },
    }}
  />
)

import { usePanoraWidget } from "@panoraexchange/widget-sdk"

const widget = usePanoraWidget()

Set the from token in the swap widget

widget.setFromTokenAddress({ tokenType: "token address" })

Set the to token in the swap widget

widget.setToTokenAddress({ tokenType: "token address" })

Open the widget token picker

widget.openTokenPicker()

Close the widget token picker

widget.closeTokenPicker()

3. Guide

Connecting Wallet

Connecting your preferred wallet to the Aptos Chain is a seamless process with our swap widget.

Click on the 'Connect Wallet' button at the top right of the widget.

Click on the wallet you want to connect to.

Accept the connection request in your wallet extension.

Selecting Token Pair

Click on any side of the token pair to change

Select the token

Swapping

Enter your desired amount in the token input box to load the swap route

To finalize the transaction, select 'Confirm Swap' and promptly approve the transaction within your wallet extension. This action ensures successful completion of the transaction process.