@perawallet/swap

Algorand swap utilities and widget integration.

Installation

npm install @perawallet/swap

Usage

Unified API

import { PeraSwap, WidgetController } from '@perawallet/swap'

// Create a PeraSwap instance for API operations
// Optional 2nd parameter lets you set a referrer URL for analytics/attribution
const peraSwap = new PeraSwap('mainnet', 'https://myapp.example')

// Widget functionality (now in WidgetController)
const widgetUrl = WidgetController.generateWidgetUrl({
  theme: 'dark',
  assetIn: 0, // ALGO
  assetOut: 31566704 // USDC
})

const iframe = WidgetController.createWidgetIframe({
  theme: 'dark'
})
document.body.appendChild(iframe)

// Swap API functionality
const quote = await peraSwap.createQuote({
  providers: ['tinyman', 'vestige-v4'],
  swapper_address: 'ABCDEF...',
  swap_type: 'fixed-input',
  asset_in_id: 0, // ALGO
  asset_out_id: 31566704, // USDC
  amount: '1000000', // 1 ALGO (in microAlgos)
  slippage: '0.005' // 0.5%
})

// Prepare transactions for signing
const transactions = await peraSwap.prepareTransactions(quote.results[0].quote_id_str)

// ... Sign and submit transactions with your wallet ...
// After successfully submitting to chain, report swap status:
await peraSwap.updateSwapStatus(String(transactions.swap_id), {
  status: 'in_progress',
  submitted_transaction_ids: ['<txid-1>', '<txid-2>']
})

// Asset management
const asset = await peraSwap.getAsset(31566704)
const assets = await peraSwap.searchAssets('USDC')
const availableAssets = await peraSwap.getAvailableAssets({ asset_in_id: 0 })

// Switch networks
peraSwap.updateNetwork('testnet')
const testnetAsset = await peraSwap.getAsset(31566704)

Note: The package uses native fetch API and has no external dependencies for HTTP requests. The PeraSwap class provides a unified interface for both widget generation and swap API operations.

Configuration

Widget Configuration

PeraSwap.generateWidgetUrl() Options

| Parameter | Description | Values | Default | |-----------|-------------|--------|---------| | network | Algorand network | 'mainnet' | 'testnet' | 'mainnet' | | theme | Widget theme | 'light' | 'dark' | 'light' | | assetIn | Input asset ID | number | string | 0 (ALGO) | | assetOut | Output asset ID | number | string | 31566704 (USDC) | | iframeBg | Background color | Hex color string | undefined | | useParentSigner | Use parent signer | boolean | false | | accountAddress | Account address (required if useParentSigner=true) | string | undefined |

API Methods

PeraSwap Class Methods (Swap API Operations)

| Method | Description | Returns | |--------|-------------|---------| | createQuote(body, signal?) | Create swap quote | Promise<{results: SwapQuote[]}> | | prepareTransactions(quoteId, depositAddress?) | Get transaction groups | Promise<PrepareTransactionsResponse> | | updateSwapStatus(swapId, body) | Update swap status | Promise<any> | | getAssets(params) | Get assets by IDs or search | Promise<GetAssetsResponse> | | getAsset(assetId) | Get single asset by ID | Promise<Asset \| null> | | searchAssets(query) | Search assets by name | Promise<Asset[]> | | getAvailableAssets(params) | Get available swap assets | Promise<{results: Asset[]}> | | getAlgoPrice() | Get ALGO price in USD | Promise<{exchange_price: string}> | | updateNetwork(network) | Switch network | void | | getNetwork() | Get current network | 'mainnet' \| 'testnet' |

WidgetController Class Methods (Widget & Communication)

| Method | Description | Returns | |--------|-------------|---------| | generateWidgetUrl(config) | Static method to generate widget URL | string | | createWidgetIframe(config, options) | Static method to create iframe element | HTMLIFrameElement | | sendMessageToWidget(data) | Static method to send messages to widget | void | | addWidgetEventListeners() | Add message event listeners | void | | removeWidgetEventListeners() | Remove message event listeners | void |

Type Definitions

The package uses string literal types for better developer experience:

type WidgetAppTheme = 'light' | 'dark'
type WidgetNetwork = 'mainnet' | 'testnet'
type SwapProvider = 'tinyman' | 'tinyman-swap-router' | 'vestige-v4'
type SwapType = 'fixed-input'

Constructor

new PeraSwap(
  network?: 'mainnet' | 'testnet',
  referrerUrl?: string
)

• referrerUrl is optional and can be used to attribute requests to your app. When provided, referrer_url is forwarded with quote requests.

Swap Status Reporting

Call updateSwapStatus after you submit signed transactions to the network.

// Success path: transactions submitted to mempool
await peraSwap.updateSwapStatus(String(prepareResponse.swap_id), {
  status: 'in_progress',
  submitted_transaction_ids: txIds // string[] of submitted tx ids
})

// Failure path: something went wrong while submitting
await peraSwap.updateSwapStatus(String(prepareResponse.swap_id), {
  status: 'failed',
  reason: 'blockchain_error' // or 'user_cancelled' | 'other'
})

Parent Signer Support

The package supports parent signer functionality, allowing the parent website to handle transaction signing:

import { WidgetController } from '@perawallet/swap'

// Generate widget URL with parent signer
const widgetUrl = WidgetController.generateWidgetUrl({
  network: 'mainnet',
  theme: 'dark',
  assetIn: 0, // ALGO
  assetOut: 31566704, // USDC
  iframeBg: '#242424',
  useParentSigner: true,
  accountAddress: 'ABCDEF...'
})

// Set up controller for handling messages
const controller = new WidgetController({
  onTxnSignRequest: async ({ txGroups }) => {
    // txGroups are already decoded Transaction[][] objects
    // Sign transactions using your wallet
    const signedTxns = await peraWallet.signTransaction(
      txGroups.map(group => group.map(txn => ({ txn })))
    )
    return signedTxns // Return Uint8Array[]
  },
  onTxnSignRequestTimeout: () => {
    console.log('Transaction signing timed out')
  },
  onSwapSuccess: (signedTxns) => {
    console.log('Swap completed with signed transactions:', signedTxns)
  }
})

// Add event listeners to handle widget messages
controller.addWidgetEventListeners()

// Don't forget to remove listeners when done
controller.removeWidgetEventListeners()

Examples

This package includes comprehensive examples demonstrating different integration approaches:

React Examples

The React examples showcase four different ways to integrate the Pera Swap Widget:

1. Widget URL Generator - Generate widget URLs for iframe embedding
2. Direct Iframe Creation - Programmatically create and manage iframes
3. Custom UI with Swap API - Build custom interfaces using the swap API
4. Parent Signer Integration - Handle transaction signing in the parent application

Running the React Examples

# Navigate to examples directory
cd examples/react

# Install dependencies
npm install

# Start development server
npm run dev

The examples are located in the examples/react/ directory and demonstrate:

• Widget configuration and customization
• API integration patterns
• Error handling and loading states
• Parent signer functionality
• TypeScript best practices

Development

npm install
npm run build
npm run dev