@txnlab/deflex 1.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,973 @@
+import { AlgorandClient } from "@algorandfoundation/algokit-utils";
+import algosdk, { Transaction, TransactionSigner } from "algosdk";
+
+//#region src/constants.d.ts
+/**
+ * Supported DEX protocols for swap routing
+ */
+declare enum Protocol {
+  TinymanV2 = "TinymanV2",
+  Algofi = "Algofi",
+  Algomint = "Algomint",
+  Pact = "Pact",
+  Folks = "Folks",
+  TAlgo = "TAlgo",
+}
+/**
+ * Deprecated protocols that are automatically excluded from routing
+ *
+ * @internal
+ */
+declare const DEPRECATED_PROTOCOLS: readonly ["Humble", "Tinyman"];
+/** Default Algod node URI for mainnet */
+declare const DEFAULT_ALGOD_URI = "https://mainnet-api.4160.nodely.dev/";
+/** Default Algod node token (empty for public nodes) */
+declare const DEFAULT_ALGOD_TOKEN = "";
+/** Default Algod node port */
+declare const DEFAULT_ALGOD_PORT = 443;
+/** Default Deflex API base URL */
+declare const DEFAULT_API_BASE_URL = "https://deflex.txnlab.dev/api";
+/** Default fee in basis points (0.15%) */
+declare const DEFAULT_FEE_BPS = 15;
+/** Maximum allowed fee in basis points (3.00%) */
+declare const MAX_FEE_BPS = 300;
+/** Default maximum transaction group size */
+declare const DEFAULT_MAX_GROUP_SIZE = 16;
+/** Default maximum routing depth (number of hops) */
+declare const DEFAULT_MAX_DEPTH = 4;
+/** Default auto opt-in setting (automatic asset/app opt-in detection) */
+declare const DEFAULT_AUTO_OPT_IN = false;
+/** Default number of rounds to wait for transaction confirmation */
+declare const DEFAULT_CONFIRMATION_ROUNDS = 4;
+//#endregion
+//#region src/types.d.ts
+/**
+ * Configuration parameters for initializing DeflexClient
+ */
+interface DeflexConfigParams {
+  /** API key for Deflex API (required) */
+  readonly apiKey: string;
+  /** Algod node URI (default: https://mainnet-api.4160.nodely.dev/) */
+  readonly algodUri?: string;
+  /** Algod node token (can be empty string for public nodes) */
+  readonly algodToken?: string;
+  /** Algod node port (default: 443) */
+  readonly algodPort?: string | number;
+  /** Referrer address for fee sharing (receives 25% of swap fees) */
+  readonly referrerAddress?: string;
+  /** Fee in basis points (default: 15 = 0.15%, max: 300 = 3.00%) */
+  readonly feeBps?: number;
+  /** Automatically detect and add required opt-in transactions (default: false) */
+  readonly autoOptIn?: boolean;
+}
+/**
+ * Internal configuration with all required fields validated
+ *
+ * @internal
+ */
+type DeflexConfig = Omit<Required<DeflexConfigParams>, 'referrerAddress'> & {
+  readonly referrerAddress: string | undefined;
+};
+/**
+ * Swap quote type determining which amount is fixed
+ */
+type QuoteType = 'fixed-input' | 'fixed-output';
+/**
+ * Parameters for requesting a swap quote from the Deflex API (raw API method)
+ */
+interface FetchQuoteParams {
+  /** Input asset ID */
+  readonly fromASAID: bigint | number;
+  /** Output asset ID */
+  readonly toASAID: bigint | number;
+  /** Amount to swap (in base units) */
+  readonly amount: bigint | number;
+  /** Quote type (default: 'fixed-input') */
+  readonly type?: QuoteType;
+  /** Protocols to exclude from routing (default: []) */
+  readonly disabledProtocols?: readonly Protocol[];
+  /** Maximum transaction group size (default: 16) */
+  readonly maxGroupSize?: number;
+  /** Maximum depth of the route (default: 4) */
+  readonly maxDepth?: number;
+  /** Whether to include asset opt-in transaction (overrides config.autoOptIn if set) */
+  readonly optIn?: boolean;
+  /** Address of the account that will perform the swap (required if autoOptIn is enabled) */
+  readonly address?: string;
+}
+/**
+ * Parameters for requesting a swap quote (class-based method)
+ */
+interface QuoteParams {
+  /** Input asset ID */
+  readonly fromAssetId: bigint | number;
+  /** Output asset ID */
+  readonly toAssetId: bigint | number;
+  /** Amount to swap (in base units) */
+  readonly amount: bigint | number;
+  /** Quote type (default: 'fixed-input') */
+  readonly type?: QuoteType;
+  /** Protocols to exclude from routing (default: []) */
+  readonly disabledProtocols?: readonly Protocol[];
+  /** Maximum transaction group size (default: 16) */
+  readonly maxGroupSize?: number;
+  /** Maximum depth of the route (default: 4) */
+  readonly maxDepth?: number;
+  /** Whether to include asset opt-in transaction (overrides config.autoOptIn if set) */
+  readonly optIn?: boolean;
+  /** Address of the account that will perform the swap (required if autoOptIn is enabled) */
+  readonly address?: string;
+}
+/**
+ * Asset information from the Deflex API
+ */
+interface Asset {
+  /** Asset ID */
+  readonly id: number;
+  /** Number of decimal places */
+  readonly decimals: number;
+  /** Unit name */
+  readonly unit_name: string;
+  /** Full asset name */
+  readonly name: string;
+  /** Price in ALGO */
+  readonly price_algo: number;
+  /** Price in USD */
+  readonly price_usd: number;
+}
+/**
+ * Profit information for a swap
+ */
+interface Profit {
+  /** Profit amount in base units */
+  readonly amount: number;
+  /** The asset in which profit is denominated */
+  readonly asa: Asset;
+}
+/**
+ * A single step in a swap route path
+ */
+interface PathElement {
+  /** Protocol name and fee tier */
+  readonly name: string;
+  /** Protocol class identifier */
+  readonly class: string[][];
+  /** Input asset */
+  readonly in: Asset;
+  /** Output asset */
+  readonly out: Asset;
+}
+/**
+ * A route with its percentage of the total swap amount
+ */
+interface Route {
+  /** Percentage of total swap amount routed through this path */
+  readonly percentage: number;
+  /** The sequence of swaps in this route */
+  readonly path: PathElement[];
+}
+/**
+ * Quote from a specific DEX protocol
+ */
+interface DexQuote {
+  /** Protocol name and fee tier */
+  readonly name: string;
+  /** Protocol class */
+  readonly class: string;
+  /** Quoted output value */
+  readonly value: number;
+}
+/**
+ * Encrypted transaction payload from the quote
+ */
+interface TxnPayload {
+  /** Initialization vector for decryption */
+  readonly iv: string;
+  /** Encrypted transaction data */
+  readonly data: string;
+}
+/**
+ * Quote response from the Deflex API
+ */
+interface FetchQuoteResponse {
+  /** The quoted output amount or input amount (depending on quote type) */
+  readonly quote: string | number;
+  /** Profit information for the swap */
+  readonly profit: Profit;
+  /** Baseline price without fees */
+  readonly priceBaseline: number;
+  /** Price impact for the user */
+  readonly userPriceImpact?: number;
+  /** Overall market price impact */
+  readonly marketPriceImpact?: number;
+  /** USD value of input amount */
+  readonly usdIn: number;
+  /** USD value of output amount */
+  readonly usdOut: number;
+  /** The routing path(s) for the swap */
+  readonly route: Route[];
+  /** Flattened view of routing percentages by protocol */
+  readonly flattenedRoute: Record<string, number>;
+  /** Individual quotes from each DEX */
+  readonly quotes: DexQuote[];
+  /** App IDs that require opt-in for this swap */
+  readonly requiredAppOptIns: number[];
+  /** Encrypted transaction payload for generating swap transactions */
+  readonly txnPayload: TxnPayload | null;
+  /** Fees charged by each protocol */
+  readonly protocolFees: Record<string, number>;
+  /** Input asset ID */
+  readonly fromASAID: number;
+  /** Output asset ID */
+  readonly toASAID: number;
+  /** Quote type */
+  readonly type: string;
+  /** Performance timing data */
+  readonly timing?: unknown;
+}
+/**
+ * Transaction signature from the Deflex API
+ */
+interface DeflexSignature {
+  /** Signature type */
+  readonly type: 'logic_signature' | 'secret_key';
+  /** Signature data */
+  readonly value: unknown;
+}
+/**
+ * Transaction data from the Deflex API
+ */
+interface DeflexTransaction {
+  /** Base64-encoded transaction data */
+  readonly data: string;
+  /** Group ID for the transaction */
+  readonly group: string;
+  /** Logic signature blob (if applicable) */
+  readonly logicSigBlob: unknown | false;
+  /** Signature data (false if user must sign) */
+  readonly signature: DeflexSignature | false;
+}
+/**
+ * Parameters for fetching executable swap transactions
+ */
+interface FetchSwapTxnsParams {
+  /** Quote response from fetchQuote() */
+  readonly quote: FetchQuoteResponse;
+  /** Algorand address that will sign the transactions */
+  readonly address: string;
+  /** Slippage tolerance as a percentage (e.g., 1 for 1%) */
+  readonly slippage: number;
+}
+/**
+ * Request body for fetching swap transactions
+ *
+ * @internal
+ */
+interface FetchSwapTxnsBody {
+  /** API key for authentication */
+  readonly apiKey: string;
+  /** Address of the account that will sign the transactions */
+  readonly address: string;
+  /** Encrypted transaction payload from the quote */
+  readonly txnPayloadJSON: TxnPayload | null;
+  /** Slippage tolerance as a percentage */
+  readonly slippage: number;
+}
+/**
+ * Response from fetching swap transactions
+ */
+interface FetchSwapTxnsResponse {
+  /** Array of transaction data */
+  readonly txns: DeflexTransaction[];
+}
+/**
+ * Processed transaction with optional pre-signature
+ *
+ * @internal
+ */
+interface SwapTransaction {
+  /** The Algorand transaction */
+  readonly txn: algosdk.Transaction;
+  /** Pre-signature from Deflex (if applicable) */
+  readonly deflexSignature?: DeflexSignature;
+}
+//#endregion
+//#region src/composer.d.ts
+/**
+ * A signer function for signing transaction groups
+ *
+ * Can be either:
+ * - A TransactionSigner: algosdk.TransactionSigner
+ * - A simpler inline function that only accepts the transaction group
+ */
+type SignerFunction = TransactionSigner | ((txns: Transaction[]) => Promise<Uint8Array[]>);
+/**
+ * Status of the SwapComposer transaction group lifecycle
+ */
+declare enum SwapComposerStatus {
+  /** The atomic group is still under construction. */
+  BUILDING = 0,
+  /** The atomic group has been finalized, but not yet signed. */
+  BUILT = 1,
+  /** The atomic group has been finalized and signed, but not yet submitted to the network. */
+  SIGNED = 2,
+  /** The atomic group has been finalized, signed, and submitted to the network. */
+  SUBMITTED = 3,
+  /** The atomic group has been finalized, signed, submitted, and successfully committed to a block. */
+  COMMITTED = 4,
+}
+/**
+ * Configuration for creating a SwapComposer instance
+ */
+interface SwapComposerConfig {
+  /** The quote response from fetchQuote() */
+  readonly quote: FetchQuoteResponse;
+  /** The swap transactions from fetchSwapTransactions() */
+  readonly deflexTxns: DeflexTransaction[];
+  /** AlgorandClient instance for blockchain operations */
+  readonly algorand: AlgorandClient;
+  /** The address of the account that will sign transactions */
+  readonly address: string;
+  /** Transaction signer function */
+  readonly signer: SignerFunction;
+}
+/**
+ * Composer for building and executing atomic swap transaction groups
+ *
+ * The SwapComposer allows you to build complex transaction groups by adding custom
+ * transactions before and after swap transactions. It handles pre-signed transactions,
+ * automatic app opt-ins, and provides a fluent API for transaction group construction.
+ *
+ * @example
+ * ```typescript
+ * const quote = await deflex.fetchQuote({ ... })
+ * const composer = await deflex.newSwap({ quote, address, slippage })
+ *
+ * await composer
+ *   .addTransaction(customTxn)
+ *   .addSwapTransactions()
+ *   .execute(signer)
+ * ```
+ */
+declare class SwapComposer {
+  /** The maximum size of an atomic transaction group. */
+  static MAX_GROUP_SIZE: number;
+  private status;
+  private transactions;
+  private swapTransactionsAdded;
+  private signedTxns;
+  private txIds;
+  private readonly quote;
+  private readonly deflexTxns;
+  private readonly algorand;
+  private readonly address;
+  private readonly signer;
+  /**
+   * Create a new SwapComposer instance
+   *
+   * Note: Most developers should use DeflexClient.newSwap() instead of constructing
+   * this directly, as the factory method handles fetching swap transactions automatically.
+   *
+   * @param config - Configuration for the composer
+   * @param config.quote - The quote response from fetchQuote()
+   * @param config.deflexTxns - The swap transactions from fetchSwapTransactions()
+   * @param config.algorand - AlgorandClient instance for blockchain operations
+   * @param config.address - The address of the account that will sign transactions
+   * @param config.signer - Transaction signer function
+   */
+  constructor(config: SwapComposerConfig);
+  /**
+   * Get the status of this composer's transaction group
+   *
+   * @returns The current status of the transaction group
+   */
+  getStatus(): SwapComposerStatus;
+  /**
+   * Get the number of transactions currently in this atomic group
+   *
+   * @returns The number of transactions in the group
+   */
+  count(): number;
+  /**
+   * Add a transaction to the atomic group
+   *
+   * Transactions are added in the order methods are called. For example:
+   * ```typescript
+   * composer
+   *   .addTransaction(txn1)      // Added first
+   *   .addSwapTransactions()     // Added second
+   *   .addTransaction(txn2)      // Added third
+   * ```
+   *
+   * @param transaction - The transaction to add
+   * @returns This composer instance for chaining
+   * @throws Error if the composer is not in the BUILDING status
+   * @throws Error if the maximum group size is exceeded
+   */
+  addTransaction(transaction: Transaction): this;
+  /**
+   * Add swap transactions to the atomic group
+   *
+   * This method automatically processes required app opt-ins and adds all swap
+   * transactions from the quote. Can only be called once per composer instance.
+   *
+   * @returns This composer instance for chaining
+   * @throws Error if the swap transactions have already been added
+   * @throws Error if the composer is not in the BUILDING status
+   * @throws Error if the maximum group size is exceeded
+   */
+  addSwapTransactions(): Promise<this>;
+  /**
+   * Sign the transaction group
+   *
+   * Automatically adds swap transactions if not already added, builds the atomic group,
+   * and signs all transactions using the configured signer.
+   *
+   * @returns A promise that resolves to an array of signed transaction blobs
+   *
+   * @example
+   * ```typescript
+   * const signedTxns = await composer.sign()
+   * ```
+   */
+  sign(): Promise<Uint8Array[]>;
+  /**
+   * Submit the signed transactions to the network
+   *
+   * This method signs the transaction group (if not already signed) and submits
+   * it to the Algorand network. Does not wait for confirmation.
+   *
+   * @returns The transaction IDs
+   * @throws Error if the transaction group has already been submitted
+   *
+   * @example
+   * ```typescript
+   * const txIds = await composer.submit()
+   * console.log('Submitted transactions:', txIds)
+   * ```
+   */
+  submit(): Promise<string[]>;
+  /**
+   * Execute the swap
+   *
+   * Signs the transaction group, submits it to the network, and waits for confirmation.
+   * This is the primary method for executing swaps and combines sign(), submit(), and
+   * waitForConfirmation() into a single call.
+   *
+   * @param waitRounds - The number of rounds to wait for confirmation (default: 4)
+   * @returns Object containing the confirmed round and transaction IDs
+   * @throws Error if the transaction group has already been committed
+   *
+   * @example
+   * ```typescript
+   * const result = await composer.execute()
+   * console.log(`Confirmed in round ${result.confirmedRound}`)
+   * console.log('Transaction IDs:', result.txIds)
+   * ```
+   */
+  execute(waitRounds?: number): Promise<{
+    confirmedRound: bigint;
+    txIds: string[];
+  }>;
+  /**
+   * Validates an Algorand address
+   */
+  private validateAddress;
+  /**
+   * Processes app opt-ins and decodes swap transactions from API response
+   */
+  private processSwapTransactions;
+  /**
+   * Creates opt-in transactions for apps the user hasn't opted into yet
+   */
+  private processRequiredAppOptIns;
+  /**
+   * Finalizes the transaction group by assigning group IDs
+   *
+   * The composer's status will be at least BUILT after executing this method.
+   */
+  private buildGroup;
+  /**
+   * Re-signs a Deflex transaction using the provided logic signature or secret key
+   */
+  private signDeflexTransaction;
+}
+//#endregion
+//#region src/quote.d.ts
+/**
+ * Configuration for creating a DeflexQuote instance
+ */
+interface DeflexQuoteConfig {
+  /** The raw quote response from the Deflex API */
+  response: FetchQuoteResponse;
+  /** The original amount from the quote request */
+  amount: bigint | number;
+  /** Optional address parameter from the quote request */
+  address?: string;
+}
+/**
+ * Wrapper class for Deflex quote responses with convenience methods
+ *
+ * The DeflexQuote class provides a developer-friendly interface for working with
+ * swap quotes from the Deflex API. It exposes all quote properties via getters
+ * and provides additional convenience methods for derived data.
+ *
+ * @example
+ * ```typescript
+ * const quote = await deflex.newQuote({
+ *   address: 'ABC...',
+ *   fromAssetId: 0,
+ *   toAssetId: 31566704,
+ *   amount: 1_000_000,
+ * })
+ *
+ * // Access quote properties directly
+ * console.log(quote.quote)              // bigint (quoted amount)
+ * console.log(quote.fromAssetId)        // number
+ * console.log(quote.toAssetId)          // number
+ *
+ * // Access metadata
+ * console.log(quote.amount)             // bigint (original request amount)
+ * console.log(quote.address)            // string | undefined
+ * console.log(quote.createdAt)          // number
+ *
+ * // Use convenience methods for derived data
+ * const minReceivedAmount = quote.getSlippageAmount(slippage) // fixed-input swap
+ * const maxSentAmount = quote.getSlippageAmount(slippage) // fixed-output swap
+ * ```
+ */
+declare class DeflexQuote {
+  private readonly _response;
+  private readonly _amount;
+  private readonly _address?;
+  private readonly _createdAt;
+  /**
+   * Create a new DeflexQuote instance
+   *
+   * Note: Most developers should use DeflexClient.newQuote() instead of constructing
+   * this directly, as the factory method handles fetching the quote automatically.
+   *
+   * @param config - Configuration for the quote instance
+   * @param config.response - The raw quote response from the Deflex API
+   * @param config.amount - The original amount from the quote request
+   * @param config.address - Optional address parameter from the quote request
+   */
+  constructor(config: DeflexQuoteConfig);
+  /**
+   * Get the raw quote response from the Deflex API
+   *
+   * @returns The raw quote response from the Deflex API
+   */
+  get response(): FetchQuoteResponse;
+  /**
+   * The original amount from the quote request (in base units)
+   *
+   * This is the amount that was provided when fetching the quote.
+   * For fixed-input swaps, this is the input amount.
+   * For fixed-output swaps, this is the desired output amount.
+   *
+   * @example
+   * ```typescript
+   * const quote = await deflex.newQuote({
+   *   fromAssetId: 0,
+   *   toAssetId: 31566704,
+   *   amount: 1_000_000, // 1 ALGO
+   *   type: 'fixed-input'
+   * })
+   * console.log(quote.amount) // 1000000n (input amount)
+   * console.log(quote.quote)  // 5000000n (output amount quoted)
+   * ```
+   */
+  get amount(): bigint;
+  /**
+   * The address parameter from the quote request
+   *
+   * This is the address that was provided when fetching the quote (if any).
+   * Useful for tracking which account the quote was fetched for, especially
+   * when using autoOptIn functionality.
+   */
+  get address(): string | undefined;
+  /**
+   * Timestamp when the quote was created (in milliseconds)
+   *
+   * Can be used to determine quote freshness. Quotes may become stale
+   * over time as market conditions change.
+   *
+   * @example
+   * ```typescript
+   * const ageInSeconds = (Date.now() - quote.createdAt) / 1000
+   * if (ageInSeconds > 30) {
+   *   console.log('Quote may be stale, consider refreshing')
+   * }
+   * ```
+   */
+  get createdAt(): number;
+  /**
+   * The quoted output amount or input amount (depending on quote type)
+   *
+   * For fixed-input swaps: This is the output amount you'll receive
+   * For fixed-output swaps: This is the input amount you'll need to provide
+   *
+   * @returns The quote amount as a bigint in base units
+   */
+  get quote(): bigint;
+  /**
+   * Profit information for the swap
+   */
+  get profit(): Profit;
+  /**
+   * Baseline price without fees
+   */
+  get priceBaseline(): number;
+  /**
+   * Price impact for the user
+   */
+  get userPriceImpact(): number | undefined;
+  /**
+   * Overall market price impact
+   */
+  get marketPriceImpact(): number | undefined;
+  /**
+   * USD value of input amount
+   */
+  get usdIn(): number;
+  /**
+   * USD value of output amount
+   */
+  get usdOut(): number;
+  /**
+   * The routing path(s) for the swap
+   */
+  get route(): Route[];
+  /**
+   * Flattened view of routing percentages by protocol
+   */
+  get flattenedRoute(): Record<string, number>;
+  /**
+   * Individual quotes from each DEX
+   */
+  get quotes(): DexQuote[];
+  /**
+   * App IDs that require opt-in for this swap
+   */
+  get requiredAppOptIns(): number[];
+  /**
+   * Encrypted transaction payload for generating swap transactions
+   */
+  get txnPayload(): TxnPayload | null;
+  /**
+   * Fees charged by each protocol
+   */
+  get protocolFees(): Record<string, number>;
+  /**
+   * Input asset ID
+   */
+  get fromAssetId(): number;
+  /**
+   * Output asset ID
+   */
+  get toAssetId(): number;
+  /**
+   * Quote type
+   */
+  get type(): string;
+  /**
+   * Performance timing data
+   */
+  get timing(): unknown | undefined;
+  /**
+   * Calculate the slippage-adjusted amount
+   *
+   * For fixed-input swaps: Returns the minimum amount you'll receive after slippage
+   * For fixed-output swaps: Returns the maximum amount you'll need to send after slippage
+   *
+   * @param slippage - Slippage tolerance as a percentage (e.g., 1 for 1%)
+   * @returns The slippage-adjusted amount as a bigint
+   *
+   * @example
+   * ```typescript
+   * // Fixed-input swap: 1 ALGO -> USDC
+   * const quote = await deflex.newQuote({
+   *   fromAssetId: 0,
+   *   toAssetId: 31566704,
+   *   amount: 1_000_000,
+   *   type: 'fixed-input'
+   * })
+   *
+   * // Get minimum output with 1% slippage
+   * const minOutput = quote.getSlippageAmount(1)
+   * console.log(`Minimum you'll receive: ${minOutput}`)
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Fixed-output swap: ALGO -> 10 USDC
+   * const quote = await deflex.newQuote({
+   *   fromAssetId: 0,
+   *   toAssetId: 31566704,
+   *   amount: 10_000_000,
+   *   type: 'fixed-output'
+   * })
+   *
+   * // Get maximum input with 1% slippage
+   * const maxInput = quote.getSlippageAmount(1)
+   * console.log(`Maximum you'll need to send: ${maxInput}`)
+   * ```
+   */
+  getSlippageAmount(slippage: number): bigint;
+}
+//#endregion
+//#region src/client.d.ts
+/**
+ * Client for interacting with the Deflex order router API
+ *
+ * The DeflexClient provides methods to fetch swap quotes and create transaction composers
+ * for executing swaps on the Algorand blockchain. It handles API communication, transaction
+ * validation, and automatic asset/app opt-in detection.
+ *
+ * @example
+ * ```typescript
+ * const deflex = new DeflexClient({
+ *   apiKey: 'your-api-key',
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const deflex = new DeflexClient({
+ *   apiKey: 'your-api-key',
+ *   algodUri: 'https://mainnet-api.4160.nodely.dev/',
+ *   algodToken: '',
+ *   algodPort: 443,
+ *   referrerAddress: 'REFERRER_ADDRESS...',
+ *   feeBps: 15,
+ *   autoOptIn: false,
+ * })
+ * ```
+ */
+declare class DeflexClient {
+  private readonly baseUrl;
+  private readonly config;
+  private readonly algorand;
+  /**
+   * Create a new DeflexClient instance
+   *
+   * @param config - Configuration parameters
+   * @param config.apiKey - API key for Deflex API (required)
+   * @param config.algodUri - Algod node URI (default: https://mainnet-api.4160.nodely.dev/)
+   * @param config.algodToken - Algod node token (default: '')
+   * @param config.algodPort - Algod node port (default: 443)
+   * @param config.referrerAddress - Referrer address for fee sharing (receives 25% of swap fees)
+   * @param config.feeBps - Fee in basis points (default: 15 = 0.15%, max: 300 = 3.00%)
+   * @param config.autoOptIn - Automatically detect and add required opt-in transactions (default: false)
+   */
+  constructor(config: DeflexConfigParams);
+  /**
+   * Fetch a swap quote from the Deflex API
+   *
+   * Requests optimal swap routing from the Deflex API. The quote includes routing
+   * information, price impact, required opt-ins, and an encrypted transaction payload.
+   *
+   * @param params - Parameters for the quote request
+   * @param params.fromASAID - The ID of the asset to swap from
+   * @param params.toASAID - The ID of the asset to swap to
+   * @param params.amount - The amount of the asset to swap in base units
+   * @param params.type - The type of the quote (default: 'fixed-input')
+   * @param params.disabledProtocols - List of protocols to disable (default: [])
+   * @param params.maxGroupSize - The maximum group size (default: 16)
+   * @param params.maxDepth - The maximum depth (default: 4)
+   * @param params.address - The address of the account that will perform the swap (recommended when using `config.autoOptIn` or `params.optIn`)
+   * @param params.optIn - Whether to include asset opt-in transaction
+   *   - If true: API reduces maxGroupSize by 1 and includes opt-in (always included, even if not needed)
+   *   - If false: No opt-in transaction included
+   *   - If undefined: Falls back to `config.autoOptIn` behavior with account check (if `params.address` is provided)
+   * @returns A FetchQuoteResponse object with routing information
+   *
+   * @example
+   * ```typescript
+   * const quote = await deflex.fetchQuote({
+   *   address: 'ABC...',
+   *   fromASAID: 0,           // ALGO
+   *   toASAID: 31566704,      // USDC
+   *   amount: 1_000_000,      // 1 ALGO
+   * })
+   * ```
+   */
+  fetchQuote(params: FetchQuoteParams): Promise<FetchQuoteResponse>;
+  /**
+   * Check if asset opt-in is required for the output asset
+   *
+   * Convenience method to determine if an address needs to opt into the output asset
+   * of a swap. This is useful when you want to get a quote without requiring wallet
+   * connection upfront, but need to know whether to set `optIn: true` in fetchQuote()
+   * to ensure proper routing (as opt-ins reduce maxGroupSize by 1).
+   *
+   * Note: If you enable `config.autoOptIn`, this check is handled automatically when
+   * an address is provided to fetchQuote().
+   *
+   * @param address - The address to check
+   * @param assetId - The output asset ID to check
+   * @returns True if asset opt-in is required, false otherwise (always false for ALGO)
+   *
+   * @example
+   * ```typescript
+   * // Check if opt-in needed for output asset before fetching quote
+   * const needsOptIn = await deflex.needsAssetOptIn(userAddress, toAssetId)
+   * const quote = await deflex.fetchQuote({
+   *   fromAssetId,
+   *   toAssetId,
+   *   amount,
+   *   optIn: needsOptIn,
+   * })
+   * ```
+   */
+  needsAssetOptIn(address: string, assetId: number | bigint): Promise<boolean>;
+  /**
+   * Fetch swap transactions from the Deflex API
+   *
+   * Decrypts the quote payload and generates executable swap transactions for the
+   * specified signer address with the given slippage tolerance.
+   *
+   * @param params - Parameters for the swap transaction request
+   * @param params.quote - The quote response from fetchQuote()
+   * @param params.address - The address of the signer
+   * @param params.slippage - The slippage tolerance as a percentage (e.g., 1 for 1%)
+   * @returns A FetchSwapTxnsResponse object with transaction data
+   */
+  fetchSwapTransactions(params: FetchSwapTxnsParams): Promise<FetchSwapTxnsResponse>;
+  /**
+   * Fetch a quote and return a DeflexQuote wrapper instance
+   *
+   * This is the recommended way to fetch quotes. It wraps the raw API response
+   * in a DeflexQuote class that provides convenient methods for accessing quote data.
+   *
+   * @param params - Parameters for the quote request
+   * @param params.fromAssetId - The ID of the asset to swap from
+   * @param params.toAssetId - The ID of the asset to swap to
+   * @param params.amount - The amount of the asset to swap in base units
+   * @param params.type - The type of the quote (default: 'fixed-input')
+   * @param params.disabledProtocols - List of protocols to disable (default: [])
+   * @param params.maxGroupSize - The maximum group size (default: 16)
+   * @param params.maxDepth - The maximum depth (default: 4)
+   * @param params.address - The address of the account that will perform the swap (recommended when using `config.autoOptIn` or `params.optIn`)
+   * @param params.optIn - Whether to include asset opt-in transaction
+   * @returns A DeflexQuote instance with convenience methods
+   *
+   * @example
+   * ```typescript
+   * const quote = await deflex.newQuote({
+   *   address: 'ABC...',
+   *   fromAssetId: 0,
+   *   toAssetId: 31566704,
+   *   amount: 1_000_000,
+   * })
+   *
+   * // Access quote data
+   * console.log(quote.quote)                 // bigint (quoted amount)
+   * console.log(quote.fromAssetId)           // number
+   * console.log(quote.toAssetId)             // number
+   *
+   * // Access metadata
+   * console.log(quote.amount)                // bigint (original request amount)
+   * console.log(quote.address)               // string | undefined
+   * console.log(quote.createdAt)             // number
+   *
+   * // Use convenience methods
+   * const minReceivedAmount = quote.getSlippageAmount(slippage) // fixed-input swap
+   * const maxSentAmount = quote.getSlippageAmount(slippage) // fixed-output swap
+   * ```
+   */
+  newQuote(params: QuoteParams): Promise<DeflexQuote>;
+  /**
+   * Create a SwapComposer instance
+   *
+   * This factory method creates a composer that allows you to add custom transactions
+   * before and after the swap transactions, with automatic handling of pre-signed transactions
+   * and opt-ins.
+   *
+   * @param config.quote - The quote response from fetchQuote() or a DeflexQuote instance
+   * @param config.address - The address of the signer
+   * @param config.slippage - The slippage tolerance
+   * @param config.signer - Transaction signer function
+   * @returns A SwapComposer instance ready for building transaction groups
+   *
+   * @example
+   * ```typescript
+   * // Basic swap
+   * const quote = await deflex.newQuote({ ... })
+   * await deflex.newSwap({ quote, address, slippage, signer })
+   *   .execute()
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Advanced swap with custom transactions
+   * const quote = await deflex.newQuote({ ... })
+   * const swap = await deflex.newSwap({
+   *   quote,
+   *   address,
+   *   slippage,
+   *   signer,
+   * })
+   *
+   * console.log(swap.getStatus()) // BUILDING
+   *
+   * const signedTxns = await swap
+   *   .addTransaction(beforeTxn)
+   *   .addSwapTransactions() // Adds swap transactions to the group
+   *   .addTransaction(afterTxn)
+   *   .sign()
+   *
+   * console.log(swap.getStatus()) // SIGNED
+   *
+   * const result = await swap.execute(waitRounds)
+   * console.log(result.confirmedRound, result.txIds)
+   *
+   * console.log(swap.getStatus()) // COMMITTED
+   * ```
+   */
+  newSwap(config: {
+    quote: DeflexQuote | FetchQuoteResponse;
+    address: string;
+    slippage: number;
+    signer: SignerFunction;
+  }): Promise<SwapComposer>;
+  /**
+   * Validates the API key
+   */
+  private validateApiKey;
+  /**
+   * Validates an Algorand address
+   */
+  private validateAddress;
+  /**
+   * Validates the fee in basis points (max 300 = 3.00%)
+   */
+  private validateFeeBps;
+}
+//#endregion
+//#region src/utils.d.ts
+/**
+ * HTTP error with status code and response data
+ */
+declare class HTTPError extends Error {
+  status: number;
+  statusText: string;
+  data: unknown;
+  constructor(status: number, statusText: string, data: unknown);
+}
+/**
+ * Make an HTTP request and parse JSON response
+ *
+ * Simple wrapper around native fetch for API calls. Throws HTTPError for
+ * non-2xx responses.
+ *
+ * @param url - The URL to request
+ * @param options - Fetch options
+ * @returns Parsed JSON response
+ * @throws HTTPError if the response status is not ok
+ */
+declare function request<T>(url: string, options?: RequestInit): Promise<T>;
+//#endregion
+export { Asset, DEFAULT_ALGOD_PORT, DEFAULT_ALGOD_TOKEN, DEFAULT_ALGOD_URI, DEFAULT_API_BASE_URL, DEFAULT_AUTO_OPT_IN, DEFAULT_CONFIRMATION_ROUNDS, DEFAULT_FEE_BPS, DEFAULT_MAX_DEPTH, DEFAULT_MAX_GROUP_SIZE, DEPRECATED_PROTOCOLS, DeflexClient, DeflexConfig, DeflexConfigParams, DeflexQuote, DeflexQuoteConfig, DeflexSignature, DeflexTransaction, DexQuote, FetchQuoteParams, FetchQuoteResponse, FetchSwapTxnsBody, FetchSwapTxnsParams, FetchSwapTxnsResponse, HTTPError, MAX_FEE_BPS, PathElement, Profit, Protocol, QuoteParams, QuoteType, Route, SignerFunction, SwapComposer, SwapComposerConfig, SwapComposerStatus, SwapTransaction, TxnPayload, request };
+//# sourceMappingURL=index.d.ts.map