> 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/special-tokens.md).

# Special Tokens & Accounts

Pre-bonding HayLaunch tokens, First Stage taxed tokens and Falcon (post-quantum) accounts swap differently. What changes, with the API and with the SDK.

Most swaps need nothing beyond a quote and its transaction group. These three cases change what you send, what the quote means, or what the group costs. Each section says what changes, then what to do with the [Swap API](/haystack-dev/haystack-router/api-order-router.md) and with the [SDK](/haystack-dev/haystack-router/sdk.md).

## Pre-bonding HayLaunch tokens

A token launched on [HayLaunch](https://hay.app) trades on its bonding curve until the curve sells out, then graduates into a Pact pool and routes like any other asset. Before it graduates, every API key can quote and swap it. `fetchAssets` lists these tokens with a [`launch` mark](/haystack-dev/haystack-router/api-order-router.md#fetch-the-list-of-supported-assets).

They behave differently from ordinary ASAs:

* **Buying credits a balance in the HayLaunch app, not an ASA in the wallet.** The swapper can claim the ASA once the token graduates. A wallet that shows only ASA holdings won't show what was bought, so show the balance from the `launch` mark (`tokenNum`), or don't list these tokens.
* **Selling spends that balance.** The swapper must sign the curve call themselves.
* **The curve leg sits at the edge of the group:** last on a buy, first on a sell. The Order Router App routes between the other asset and the token's bonding asset (`bondingTokenId`: ALGO, or an ASA). When the other asset is the bonding asset, the swap is the curve call alone.
* **Fixed-input only.** A swap between two pre-bonding tokens isn't supported, and neither token can be an intermediate hop.
* **The quote needs the slippage you will execute with.** Each leg spends the floor of the leg before it, so the quote is priced on those floors. Without it, the quote is high by about the slippage.
* **Part of the bonding asset can stay behind.** What the leg before the curve delivers above its floor stays in the swapper's wallet as the bonding asset, reported in the quote as `launch.bondingSurplus`.
* **The output always goes to the swapper on a buy**, so `beneficiary` is rejected. On a sell it is honored only when the payout routes to another asset.

### With the API

Pass `slippage` to `fetchQuote`, the same value you will pass to `fetchExecuteSwapTxns`. The quote's [`launch`](/haystack-dev/haystack-router/api-order-router.md#response-fields) field describes the curve leg.

### With the SDK

Version 3.0.0 and later. Pass `slippage` to `newQuote()` as well as `newSwap()`; the SDK warns when the two differ. The quote's `launch` field and `getSummary().launch` describe the curve leg. A buy's output is read from the curve call, not the wallet's holdings.

## First Stage taxed tokens

First Stage tokens (MOOJ, DUMBLY, DEAL, STACKED and others) are frozen in the wallets of holders registered with First Stage, and charge a tax to move. On [V4](/haystack-dev/haystack-router/architecture/order-router-app-v4.md), the router handles them itself: when a swap's input or output is one of these tokens and the swapper's holding is frozen, the transaction group includes First Stage's own calls (unfreeze before the swap; the tax payment and refreeze after), and the quote accounts for the tax.

* **The quote needs the swapper's address**, so the router can check whether the holding is frozen. Without it, the swap is quoted and built without First Stage's calls, which fails on chain for a frozen holding. A holding that isn't frozen moves without First Stage's calls or tax.
* **`quote` is net of the tax.** A `fixed-input` sell swaps the amount less its sell tax, and `quote` is what the swapper receives; a `fixed-output` buy routes enough that the swapper keeps at least `amount` after the buy tax. The taxes are reported in the quote's `firstStage` field; show them to your users, since the quote alone reads as a worse price (a MOOJ sale quotes about 9% less).
* **How the tax is paid.** It is a transfer of the token from the swapper to First Stage inside the group, not part of the swap: a sell pays it out of the holding beside the swap's input (selling 1,000 MOOJ at 9% sends 90 to First Stage and swaps 910), a buy out of what arrived. The router's fee applies to the swap only. First Stage's calls add 0.028 to 0.031 ALGO of network fees, by how the token settles its tax, paid by the swapper's transactions like the rest of the group's. First Stage pays a referral share of its own protocol fee to the Haystack treasury; it costs the swapper nothing.
* **Slippage protects the swap, not the tax**, which is fixed when the group is built. A `fixed-input` sell's tax is on the request. A `fixed-input` buy's tax is charged on the quote's expected output, and slippage comes off the output before the tax: the least the swapper keeps is `(quote + toTax) × (1 − slippage) − toTax` (First Stage refunds overpaid tax only in whole tokens). A `fixed-output` buy's tax is sized so the swapper keeps at least `amount`.
* **Sell `fixed-input`.** A `fixed-output` sell from a frozen holding is rejected: the input the route doesn't spend comes back to the holding, which First Stage refuses.
* **A `fixed-output` buy of a token with a buy tax needs a pool between the pair**, through which the router swaps any surplus back. Without one the quote is rejected; quote the buy `fixed-input` instead.
* **Don't add First Stage's calls yourself** (for example with a First Stage SDK middleware): the group would hold them twice and fail. Integrations that already do were left on their own wrap; contact TxnLab to switch.
* **The output must go to the swapper's own holding** when it is frozen: a `beneficiary` whose holding of the output is frozen is rejected, since only that account can sign First Stage's calls.
* Each wrapped side takes 3 to 6 transactions of the group, which the quote reserves.

### With the API

Pass `address` to `fetchQuote`. The quote's [`firstStage`](/haystack-dev/haystack-router/api-order-router.md#response-fields) field gives `fromTax` and `toTax`, in base units of each side's asset, and `wrapped`, the sides wrapped in First Stage's calls.

### With the SDK

Version 3.4.0 and later send `address` with the quote request. `quote.firstStage` gives the taxes (`fromTax` and `toTax`, as bigints in base units of each side's asset) and the wrapped sides; `quote` is already net of them.

```typescript
const quote = await router.newQuote({ fromASAID: 2154668640, toASAID: 0, amount: 1_000_000_000, address: activeAddress })
if (quote.firstStage) {
  console.log(`First Stage tax: ${quote.firstStage.fromTax} MOOJ base units, out of the quote already`)
}
```

## Falcon (post-quantum) accounts

A transaction signed with a Falcon-1024 key costs 3 fee units (0.003 ALGO at the minimum fee) instead of 1. Passkey accounts and Pera and Lute quantum accounts sign with one. Fees pool across a group, so the group's fees must cover 0.002 ALGO more for every transaction the account signs, or the network rejects it. The swapper pays it, with the rest of the group's fees.

* **Say the account is Falcon when you quote.** The router can't tell from the address: an unused Falcon account looks like any other, and a rekeyed account signs with its auth address's key. With use-wallet, an account is Falcon when `getSignatureType(account.emptySignature) === 'pqsig'`.
* **The swapper's input transfer carries it**: its fee rises by 0.002 ALGO for every transaction in the group the swapper signs (the input itself, the opt-ins and payments ahead of it, and a HayLaunch or First Stage leg's calls). A trade with no Order Router call (a pre-bonding HayLaunch token bought or sold directly for its bonding asset) puts it on the swapper's first payment or asset transfer instead. No transaction is added. Route choice counts it too.
* **Transactions you add to the group are yours to account for**: add 0.002 ALGO to the input transfer's fee for each one the swapper signs, before assigning the group ID. Don't raise fees or regroup after receiving the group without re-signing the router's own transactions with the key it returns.

### With the API

* **Pass `signerType=falcon` to `fetchQuote`.** The quote echoes `signerType: "falcon"` when the router supports it.
* **Check `fetchExecuteSwapTxns`'s** [**`signerType`**](/haystack-dev/haystack-router/api-order-router.md#fetch-the-transaction-group-for-a-given-haystack-quote): `"falcon"` when the group's fees include the extra fee. Without it, they don't, even if the quote echoed it (a server mid-update can build without it), so add 0.002 ALGO to the input transfer's fee for every transaction the swapper signs yourself.

### With the SDK

Version 3.5.0 and later. Pass `signerType: 'falcon'` to `newQuote()`. The router includes the extra fee in the transactions it builds, and the `SwapComposer` adds it for the ones it adds (app opt-ins, middleware's `beforeSwap`/`afterSwap` transactions, `addTransaction()` and `addMethodCall()`), all on the swap's input transfer, before the group ID is assigned. `getSummary().totalFees` and the fees of `buildGroup()`'s transactions include it.

```typescript
import { getSignatureType } from '@txnlab/use-wallet'

const falcon = getSignatureType(activeAccount.emptySignature) === 'pqsig'
const quote = await router.newQuote({
  fromASAID: 0,
  toASAID: 31566704,
  amount: 1_000_000,
  address: activeAddress,
  signerType: falcon ? 'falcon' : 'ed25519',
})
```

The SDK counts the transactions sent from the swap's `address`. `newSwap()` reads whether the router's transactions include the extra fee from `fetchExecuteSwapTxns`'s `signerType`, not from the quote. When they don't (a router mid-update), it adds the extra fee for all of them itself.

With `fetchQuote()`, pass `signerType` to `newSwap()` too: a quote from a router that doesn't support it doesn't say it was requested for a Falcon signer.

```typescript
const raw = await router.fetchQuote({ ...params, signerType: 'falcon' })
const swap = await router.newSwap({ quote: raw, address: activeAddress, slippage: 1, signer: transactionSigner, signerType: 'falcon' })
```
