@txnlab/haystack-router 2.0.4 → 3.0.0

package/README.md

@@ -10,16 +10,23 @@ TypeScript/JavaScript SDK for [Haystack Order Router](https://txnlab.gitbook.io/
 
 ## Prerequisites
 
-- **Haystack Router API Key** - Request an API key by emailing [support@txnlab.dev](mailto:support@txnlab.dev)
+- **Haystack Router API Key** - A free tier key is included below for development and testing (60 requests/min). For production rate limits, request a dedicated key from [support@txnlab.dev](mailto:support@txnlab.dev).
 - algosdk 3.0.0 or later
 
+### API Key Tiers
+
+| Tier | Key | Rate Limit | Use Case |
+| --- | --- | --- | --- |
+| **Free** | `1b72df7e-1131-4449-8ce1-29b79dd3f51e` | 60 requests/min | Development, testing, low-volume integrations |
+| **Production** | Request from [support@txnlab.dev](mailto:support@txnlab.dev) | Higher limits | Production applications |
+
 ## Installation
 
 ```bash
 npm install @txnlab/haystack-router algosdk
 ```
 
-> **Note**: `algosdk` is a peer dependency and must be installed alongside `@txnlab/haystack-router`.
+> **Note**: Requires Node.js 22 or later. `algosdk` is a peer dependency and must be installed alongside `@txnlab/haystack-router`.
 
 ## Quick Start
 
@@ -31,7 +38,7 @@ const { activeAddress, transactionSigner } = useWallet()
 
 // Initialize the client
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
 })
 
 // Get a quote
@@ -63,12 +70,12 @@ import { RouterClient } from '@txnlab/haystack-router'
 
 // Basic initialization
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
 })
 
 // Custom Algod configuration
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
   algodUri: 'https://mainnet-api.4160.nodely.dev/',
   algodToken: '',
   algodPort: 443,
@@ -77,7 +84,7 @@ const router = new RouterClient({
 
 // Earn fees with the referral program
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
   referrerAddress: 'YOUR_ALGORAND_ADDRESS', // Earns 25% of swap fees
   feeBps: 15, // 0.15% fee (max: 300 = 3%)
 })
@@ -142,6 +149,41 @@ console.log('Input transaction ID:', inputTxId)
 
 The `note` is applied only to the user-signed payment or asset transfer transaction (not pre-signed or middleware transactions). The transaction ID is available after calling `buildGroup()`, `sign()`, or `execute()`.
 
+### Launch Tokens (Pre-Bonding)
+
+API keys with launch-token access can swap any asset into or out of a HayLaunch token that is still on its bonding curve. Quote it like any other asset, as a `fixed-input` swap, and pass the same `slippage` you will execute with:
+
+```typescript
+const quote = await router.newQuote({
+  fromASAID: 31566704, // USDC
+  toASAID: launchTokenAssetId, // pre-bonding launch token
+  amount: 10_000_000,
+  slippage: 1, // same value as newSwap() below
+  address: activeAddress,
+})
+
+if (quote.launch) {
+  // quote.quote: launch tokens out (buy) or output asset (sell)
+  // quote.launch.bondingSurplus: bonding asset left in the wallet
+  // quote.launch.refund: bonding asset refunded when a buy completes bonding
+}
+
+const swap = await router.newSwap({
+  quote,
+  address: activeAddress,
+  signer: transactionSigner,
+  slippage: 1,
+})
+await swap.execute()
+
+const summary = swap.getSummary()
+// summary.outputAmount: launch tokens credited (buy)
+// summary.inputAmount: launch tokens sold (sell)
+// summary.launch: the curve call's ID, bonding amount and refund
+```
+
+Without `slippage`, a launch quote overstates the output by about the slippage; `newSwap()` logs a warning when the two don't match. Fixed-output launch buys and launch-token-to-launch-token swaps aren't supported yet and return a 400.
+
 ### Transaction Signing
 
 The SDK supports both standard `algosdk.TransactionSigner` and ARC-1 compliant signer functions.
@@ -265,7 +307,7 @@ const firstStage = new FirstStageMiddleware({
 
 // Pass middleware to RouterClient
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
   middleware: [firstStage], // Middleware is applied automatically
 })
 
@@ -293,7 +335,7 @@ const autoOptOut = new AutoOptOutMiddleware({
 })
 
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
   middleware: [autoOptOut],
 })
 
@@ -314,7 +356,7 @@ If you're not using `autoOptIn: true`, you can manually check if opt-in is neede
 
 ```typescript
 const router = new RouterClient({
-  apiKey: 'your-api-key',
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
   autoOptIn: false, // Default if not provided
 })
 
@@ -402,6 +444,7 @@ async newQuote(params: FetchQuoteParams): Promise<SwapQuote>
 | `maxGroupSize`      | Maximum transactions in atomic group       | `number`                          | `16`            |
 | `maxDepth`          | Maximum swap hops                          | `number`                          | `4`             |
 | `optIn`             | Override auto opt-in behavior              | `boolean`                         | `undefined`     |
+| `slippage`          | Slippage % you will execute with, in [0, 100); required for accurate launch token quotes | `number` | `undefined` |
 
 #### RouterClient.newSwap()
 
@@ -443,6 +486,8 @@ Plain object returned by [`newQuote()`](#routerclientnewquote). Extends the raw
 | `quote`     | Quoted amount (coerced to `bigint`) | `bigint`              |
 | `amount`    | Original request amount             | `bigint`              |
 | `address`   | User address (if provided)          | `string \| undefined` |
+| `slippage`  | Slippage sent with the quote request (if provided) | `number \| undefined` |
+| `launch`    | Bonding-curve details for a pre-bonding launch token (amounts as `bigint`) | `SwapLaunchQuote \| undefined` |
 | `createdAt` | Timestamp when quote was created    | `number`              |
 
 **All properties from API response:**

package/dist/{debug-8aRsrfhx.mjs → debug-CU-Ps4nm.mjs}

@@ -1,5 +1,4 @@
-import { t as Logger } from "./logger-DUVOA2Oo.mjs";
-
+import { t as Logger } from "./logger-BelK6H0R.mjs";
 //#region src/debug.ts
 /**
 * Debug utilities for swap execution failures
@@ -16,6 +15,7 @@ function logSwapExecutionFailure(context, error) {
 			fromASAID: context.quote.fromASAID,
 			toASAID: context.quote.toASAID,
 			type: context.quote.type,
+			amount: "amount" in context.quote ? context.quote.amount.toString() : void 0,
 			quote: context.quote.quote.toString(),
 			requiredAppOptIns: context.quote.requiredAppOptIns,
 			route: context.quote.route?.map((r) => ({
@@ -32,7 +32,7 @@ function logSwapExecutionFailure(context, error) {
 		}
 	});
 }
-
 //#endregion
 export { logSwapExecutionFailure };
-//# sourceMappingURL=debug-8aRsrfhx.mjs.map
+
+//# sourceMappingURL=debug-CU-Ps4nm.mjs.map

package/dist/debug-CU-Ps4nm.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-CU-Ps4nm.mjs","names":[],"sources":["../src/debug.ts"],"sourcesContent":["/**\n * Debug utilities for swap execution failures\n * @internal\n */\n\nimport { Logger } from './logger'\nimport type { SwapQuote, FetchQuoteResponse } from './types'\n\n/**\n * Context for swap execution debugging\n */\nexport interface SwapExecutionContext {\n  quote: SwapQuote | FetchQuoteResponse\n  address: string\n  slippage: number\n  transactionCount: number\n  middlewareCount: number\n  groupSize: number\n}\n\n/**\n * Log detailed context when a swap execution fails\n * Only logs when debug level is enabled\n */\nexport function logSwapExecutionFailure(\n  context: SwapExecutionContext,\n  error: unknown,\n): void {\n  Logger.debug('Swap execution failed', {\n    error: error instanceof Error ? error.message : String(error),\n    quote: {\n      fromASAID: context.quote.fromASAID,\n      toASAID: context.quote.toASAID,\n      type: context.quote.type,\n      amount:\n        'amount' in context.quote ? context.quote.amount.toString() : undefined,\n      quote: context.quote.quote.toString(),\n      requiredAppOptIns: context.quote.requiredAppOptIns,\n      route: context.quote.route?.map((r) => ({\n        percentage: r.percentage,\n        path: r.path.map((p) => p.name).join(' → '),\n      })),\n    },\n    swap: {\n      address: context.address,\n      slippage: context.slippage,\n      transactionCount: context.transactionCount,\n      middlewareCount: context.middlewareCount,\n      groupSize: context.groupSize,\n    },\n  })\n}\n"],"mappings":";;;;;;;;;;AAwBA,SAAgB,wBACd,SACA,OACM;CACN,OAAO,MAAM,yBAAyB;EACpC,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EAC5D,OAAO;GACL,WAAW,QAAQ,MAAM;GACzB,SAAS,QAAQ,MAAM;GACvB,MAAM,QAAQ,MAAM;GACpB,QACE,YAAY,QAAQ,QAAQ,QAAQ,MAAM,OAAO,SAAS,IAAI,KAAA;GAChE,OAAO,QAAQ,MAAM,MAAM,SAAS;GACpC,mBAAmB,QAAQ,MAAM;GACjC,OAAO,QAAQ,MAAM,OAAO,KAAK,OAAO;IACtC,YAAY,EAAE;IACd,MAAM,EAAE,KAAK,KAAK,MAAM,EAAE,IAAI,CAAC,CAAC,KAAK,KAAK;GAC5C,EAAE;EACJ;EACA,MAAM;GACJ,SAAS,QAAQ;GACjB,UAAU,QAAQ;GAClB,kBAAkB,QAAQ;GAC1B,iBAAiB,QAAQ;GACzB,WAAW,QAAQ;EACrB;CACF,CAAC;AACH"}