GitHub - TxnLab/haystack-js: TypeScript/JavaScript SDK for Haystack Order Router - smart order routing and DEX aggregation on Algorand

Note: This package was formerly known as @txnlab/deflex. If you're migrating from the old package, see the migration guide.

This repository contains the Haystack Router SDK and example implementations for integrating Haystack Order Router into your applications.

Packages

@txnlab/haystack-router

TypeScript/JavaScript SDK for Haystack Order Router - smart order routing and DEX aggregation on Algorand.

Documentation: packages/haystack/README.md
npm: @txnlab/haystack-router

Examples

The examples directory contains complete working implementations:

React

Simple React application demonstrating basic Haystack Router SDK integration.

React 18 with TypeScript and Vite
Multiple wallet support (Pera, Defly, Lute)
Complete swap UI with quote display

React Query

Advanced React application showcasing TanStack Query integration.

Automatic quote fetching with debouncing
Real-time quote updates (refreshes every 15 seconds)
Optimistic UI updates with mutations
Demonstrates modern data fetching patterns

Node.js CLI

Command-line tool for executing swaps without a browser.

Custom signer implementation
Environment variable configuration
Detailed console output
Perfect for automation and scripts

Development Setup

This is a pnpm workspace monorepo. All packages and examples share dependencies and can reference each other.

Prerequisites

Haystack Router API Key - An API key is included for free tier usage (60 requests/min). For production rate limits, request a key from support@txnlab.dev.
algosdk 3.0.0 or later (peer dependency)
Node.js >= 20
pnpm 10.20.0 or later

Installation

Install all dependencies:

Building the SDK

Build the SDK package:

Running Examples

Each example can be run independently. Navigate to the example directory and follow its README:

# React
cd examples/react
pnpm dev

# React Query
cd examples/react-query
pnpm dev

# Node.js CLI
cd examples/node-cli
pnpm dev

Quick Start

Install the SDK in your project:

npm install @txnlab/haystack-router algosdk

Basic usage:

import { RouterClient } from '@txnlab/haystack-router'
import { useWallet } from '@txnlab/use-wallet-react'

const { activeAddress, transactionSigner } = useWallet()

// Initialize client
const router = new RouterClient({
	apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
})

// Get quote
const quote = await router.newQuote({
	fromASAID: 0, // ALGO
	toASAID: 31566704, // USDC
	amount: 1_000_000, // 1 ALGO
	address: activeAddress,
})

// Execute swap
const swap = await router.newSwap({
	quote,
	address: activeAddress,
	signer: transactionSigner,
	slippage: 1, // 1%
})
const result = await swap.execute()

Testing

Run SDK tests:

Run tests with coverage:

Scripts

Root-level scripts:

pnpm build - Build the SDK package
pnpm test - Run SDK tests
pnpm test:watch - Run tests in watch mode
pnpm test:coverage - Run tests with coverage
pnpm lint - Lint SDK code
pnpm format - Check code formatting
pnpm format:fix - Fix code formatting
pnpm typecheck - Type check SDK
pnpm ci - Run all CI checks (build, lint, format, test)
pnpm release - Release a new version

Documentation

SDK Documentation: packages/haystack/README.md
Examples Guide: examples/README.md
API Docs: https://txnlab.gitbook.io/haystack-router

Contributing

Contributions are welcome! The monorepo structure makes it easy to:

Make changes to the SDK in packages/haystack/
Test changes immediately in any example project
Examples automatically use the local SDK via workspace protocol

All examples reference the SDK using "@txnlab/haystack-router": "workspace:*" in their package.json.

License

MIT - see LICENSE for details

Support

Built by TxnLab