> For the complete documentation index, see [llms.txt](https://txnlab.gitbook.io/haystack-dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://txnlab.gitbook.io/haystack-dev/haystack-router/sdk.md).

# SDK

Haystack Router has SDKs to make integration as seamless as possible.

## TypeScript / JavaScript

The [`@txnlab/haystack-router`](https://www.npmjs.com/package/@txnlab/haystack-router) package wraps the [API](/haystack-dev/haystack-router/api-order-router.md): it fetches quotes, builds the transaction group, and signs and submits it with any `algosdk`-compatible signer (e.g. [use-wallet](https://github.com/TxnLab/use-wallet)).

{% embed url="<https://github.com/TxnLab/haystack-js>" %}

### Installation

```bash
npm install @txnlab/haystack-router algosdk
```

Requires `algosdk` 3.0.0 or later and Node.js 20 or later.

### Quick start

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

const { activeAddress, transactionSigner } = useWallet()

const router = new RouterClient({
  apiKey: 'hay_pk_4zhj33wahuxfplteyif5xpcgnm', // Free tier (60 requests/min)
})

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

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

The repository includes example integrations for React, React with TanStack Query, and a Node.js CLI.

{% hint style="danger" %}
**Don't call `newQuote()` to show prices.** Each quote searches routes for one exact trade, so it is slow and uses up your rate limit. Quote only for a swap the user is about to make. For prices, use the [Haystack API](/haystack-dev/haystack-api/assets.md#prices). See [Prices: use the Haystack API](/haystack-dev/haystack-router/api-order-router.md#prices-use-the-haystack-api).
{% endhint %}

### Order Router App V4

Version 3.2.0 and later support groups for the [V4 Order Router App](/haystack-dev/haystack-router/architecture/order-router-app-v4.md):

* They find the swapper's input transfer in a V4 group.
* `getSummary()` reads the output from the `route` call's `Swap` event.

Earlier versions misreport the input and output of V4 swaps, and every API key has executed through V4 since November 5, 2026, so upgrade.

### API key header

Version 3.3.0 and later send the API key in the [`X-API-Key` header](/haystack-dev/haystack-router/api-order-router.md#api-keys-and-rate-limits) instead of the URL, so the key stays out of logs and browser history. Earlier versions send it as the `apiKey` query parameter and body field, which keep working.

### Pre-bonding HayLaunch tokens

Version 3.0.0 and later can swap tokens still on their HayLaunch bonding curve. Pass `slippage` to `newQuote()` as well as `newSwap()`. See [Special Tokens & Accounts](/haystack-dev/haystack-router/special-tokens.md#pre-bonding-haylaunch-tokens).

### First Stage taxed tokens

Version 3.4.0 and later send `address` with the quote request, so the router can wrap swaps from a frozen holding; `quote.firstStage` gives the taxes. Don't also use a First Stage middleware. See [Special Tokens & Accounts](/haystack-dev/haystack-router/special-tokens.md#first-stage-taxed-tokens).

### Falcon (post-quantum) accounts

Version 3.5.0 and later add a Falcon signer's extra fees. Pass `signerType: 'falcon'` to `newQuote()`. See [Special Tokens & Accounts](/haystack-dev/haystack-router/special-tokens.md#falcon-post-quantum-accounts).

For an API key with a higher rate limit, see [Getting a key](/haystack-dev/getting-started/api-keys.md#getting-a-key) for what to send us.
