BTR Swap is a liquidity meta-aggregator powering monochain and cross-chain swaps, blending liquidity and bridge aggregators. Inspired by LlamaSwap, server-side friendly and cross-chain capable.

ESM compliant, feather light, BTR Swap can be embedded in any front-end or back-end application through:

• SDK: For Node.js, Bun, Deno back-ends and browser front-ends, whether your app uses Ethers or Viem
• CLI: Quick integration with any existing back-end or scripts

⚠️ Disclaimer

This aggregator is under active development and provided "as-is". Underlying API changes may not be immediately reflected in the repository. BTR team members are not liable for financial losses incurred from using this codebase.

We welcome issues for bugs or feature requests, and pull requests to improve the package. See CONTRIBUTING.md.

Features

• Unified Interface: Single API for monochain and cross-chain swaps
• Any Chain, Any Token: Aggregates liquidity and bridges for token swaps across any supported chains and tokens
• Best Route Selection: Finds optimal quotes across multiple aggregators
• Zero Dependencies: Lightweight implementation for any environment
• Type Safety: Comprehensive TypeScript support
• Multi-Platform: Works in Node.js, Bun, Deno and browsers

Supported Aggregators

Meta-Aggregators (cross-chain capable)

• Li.Fi stable tested
• Squid Router stable tested
• Socket stable tested
• Rango stable tested
• Unizen stable tested
• RocketX planned

Passive Liquidity Aggregators

• 1inch stable tested
• 0x stable tested
• ParaSwap stable tested
• Odos stable tested
• KyberSwap stable tested
• OpenOcean stable tested
• Firebird stable tested

JIT / Intent-Based / RFQ

Offer MEV protection, gasless swaps, and off-chain liquidity with specific handling requirements

• CowSwap planned
• Hashflow planned
• 1inch Fusion planned
• ParaSwap Delta planned
• Bebop planned
• DeBridge planned
• AirSwap disabled

Installation

SDK Installation

For integrating into JavaScript/TypeScript applications:

# npm
npm install @btr-supply/swap

# yarn
yarn add @btr-supply/swap

# bun
bun add @btr-supply/swap

CLI Installation (Optional)

For command-line usage:

# Global installation
npm install -g @btr-supply/swap-cli

# Or via npx without installing
npx @btr-supply/swap-cli quote --help

Usage

SDK Usage (Node.js, Bun, Deno)

import { getBestTransactionRequest, AggId } from "@btr-supply/swap";

async function fetchSwapQuote() {
  const params = {
    input: {
      chainId: 1, // Ethereum
      address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
      symbol: "ETH",
      decimals: 18,
      name: "Ethereum",
    },
    output: {
      chainId: 10, // Optimism (for cross-chain)
      address: "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1", // DAI
      symbol: "DAI",
      decimals: 18,
      name: "Dai Stablecoin",
    },
    inputAmountWei: BigInt("1000000000000000000"), // 1 ETH
    payer: "0xYourWalletAddress",
    maxSlippage: 50, // 0.5%
    aggIds: [AggId.LIFI, AggId.SQUID], // Optional: specify aggregators
  };

  const quote = await getBestTransactionRequest(params);
  // Use quote with your provider: provider.sendTransaction(quote);
}

Front-end Integration

import { getBestTransactionRequest, AggId } from "@btr-supply/swap";

// In a React component
async function handleSwap() {
  try {
    setLoading(true);

    const params = {
      input: {
        chainId: 1,
        address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE", // ETH
        symbol: "ETH",
        decimals: 18,
        name: "Ethereum",
      },
      output: {
        chainId: 1,
        address: "0x6B175474E89094C44Da98b954EedeAC495271d0F", // DAI
        symbol: "DAI",
        decimals: 18,
        name: "Dai Stablecoin",
      },
      inputAmountWei: BigInt(amount),
      payer: address,
      maxSlippage: 30, // 0.3%
    };

    const quote = await getBestTransactionRequest(params);

    // Send via ethers, web3.js, viem, or wagmi
    const tx = await walletClient.sendTransaction(quote);
  } catch (error) {
    console.error("Swap failed:", error);
  } finally {
    setLoading(false);
  }
}

CLI Usage

Note: The following CLI commands require prior installation of @btr-supply/swap-cli as shown above.

# Basic same-chain swap (ETH -> DAI on Ethereum)
btr-swap quote \
  --input 1:0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE:ETH:18 \
  --output 1:0x6B175474E89094C44Da98b954EedeAC495271d0F:DAI:18 \
  --input-amount 1e18 \
  --payer 0xYourWalletAddress \
  --aggregators LIFI

# Cross-chain swap (ETH on Ethereum -> DAI on Optimism)
btr-swap quote \
  --input 1:0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE:ETH:18 \
  --output 10:0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1:DAI:18 \
  --input-amount 1e18 \
  --payer 0xYourWalletAddress \
  --aggregators LIFI,SQUID \
  --serialization TABLE \
  --display RANK,ALL_COMPACT \
  --env-file ./custom.env

# Specify integrator IDs and API keys
btr-swap quote \
  --input 137:0x...:MATIC:18 \
  --output 1:0x...:DAI:18 \
  --input-amount 5e17 \
  --payer 0x... \
  --aggregators RANGO,LIFI \
  --integrator-ids '{"LIFI":"integrator-id"}' \
  --api-keys '{"RANGO":"api-key"}' \
  --serialization TABLE

# Get help
btr-swap quote --help

CLI Parameters:

• --input <chainId:address:symbol:decimals> - Input token information
• --output <chainId:address:symbol:decimals> - Output token information
• --input-amount <amount> - Amount in wei (supports scientific notation)
• --payer <address> - Sender wallet address
• --receiver <address> - Receiver address (defaults to payer)
• --max-slippage <bps> - Maximum slippage in basis points (default: 50 for 0.5%)
• --aggregators <ids> - Comma-separated aggregator IDs
• --api-keys <json> - JSON string of API keys by aggregator
• --referrer-codes <json> - JSON string of referrer codes by aggregator
• --integrator-ids <json> - JSON string of integrator IDs by aggregator
• --fees-bps <json> - JSON string of fee basis points by aggregator
• --display <modes> - Output display modes (ALL, BEST, ALL_COMPACT, BEST_COMPACT, RANK)
• --serialization <mode> - Output format (JSON, CSV, TABLE)
• --env-file <path> - Custom .env file path

Development & Testing

# Clone and setup
git clone https://github.com/btr-supply/btr-swap.git && cd btr-swap
bun install

# Development tasks
bun run lint: Run `oxlint` to check for code style and potential issues.
bun run lint:fix: Run `oxlint --fix` to automatically fix linting and formatting issues.
bun run typecheck: Check TypeScript types across all packages.
bun run build: Build all packages
bun run test: Run all tests

Build and Publish Process

The project uses a monorepo structure with the following packages:

• @btr-supply/swap - Core SDK (packages/core)
• @btr-supply/swap-cli - CLI tool (packages/cli)

# Build all packages
bun run build: Builds both SDK and CLI

# Pre-commit checks
bun run pre-commit: Runs `oxlint --fix`, `clean`, `build`, and `test:unit`. Recommended before committing changes.

# Publish packages
bun run publish:patch: Runs `pre-commit`, bumps the patch version, and publishes packages to npm.
bun run publish:minor: Runs `pre-commit`, bumps the minor version, and publishes packages to npm.
bun run publish:major: Runs `pre-commit`, bumps the major version, and publishes packages to npm.

# Install CLI globally from local build
bun run install:cli

The pre-commit process ensures:

1. Code formatting and linting (oxlint)
2. Clean and fresh builds
3. Version synchronization across packages
4. Unit tests pass

This process is automatically executed by:

• Git pre-commit hooks (via Husky)
• Publishing commands

About

BTR Swap enhances the AstrolabDAO/swapper codebase with:

• Extended aggregator support
• Advanced API keys management
• Optimized performance
• Enhanced error handling
• Enhanced logging
• BTR Swap CLI for easy server-side and script integration

License

MIT

Contributing

We welcome contributions to BTR Swap! Please see CONTRIBUTING.md for detailed guidelines on how to contribute, including:

• Branch naming and commit message conventions
• Pull request process
• Coding standards and testing requirements
• Issue formatting guidelines

All contributors are expected to follow our contribution guidelines to maintain project quality and consistency.