@pafi-dev/trading 0.3.3 → 0.4.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { Address, PublicClient, Hex } from 'viem';
-import { PartialUserOperation, PoolKey, QuoteResult, PathKey, BestQuote } from '@pafi-dev/core';
+import { Address, PublicClient, Hex, WalletClient, TransactionReceipt } from 'viem';
+import { PartialUserOperation, PoolKey, QuoteResult, PathKey, BestQuote, ExactOutputBestQuote, ExactOutputQuoteResult, BROKER_HASHES } from '@pafi-dev/core';
 export { PAFI_SUBGRAPH_URL, fetchPafiPools } from '@pafi-dev/core';
 
 interface ApiQuoteRequest {
@@ -102,6 +102,95 @@ interface ApiSwapResponse {
     feeAmountUsed: bigint;
     feeRecipient: Address;
 }
+interface ApiQuoteExactOutRequest {
+    chainId: number;
+    /** Token user is spending. */
+    inputTokenAddress: Address;
+    /** Token user wants to receive. */
+    outputTokenAddress: Address;
+    /** Exact OUTPUT token amount the user wants (raw decimals). */
+    amount: bigint;
+    /** Pools to include in routing. Combined with COMMON_POOLS. */
+    pools?: PoolKey[];
+}
+interface ApiQuoteExactOutResponse {
+    /** Echoes `request.amount` — the exact output amount. */
+    outputAmount: bigint;
+    /**
+     * Gross input required from the V4 quoter — before operator fee. Use
+     * for "you'll pay ~X PT for exactly Y USDT" UI; do not promise this
+     * number without slippage bounding. 0n when `quoteError` set.
+     */
+    estimatedInputAmount: bigint;
+    /**
+     * Total input the user must hold = `estimatedInputAmount + feeAmountInput`.
+     * Display this as the "you pay" number alongside the exact output amount.
+     */
+    inputGross: bigint;
+    /**
+     * Operator gas fee charged on the INPUT token side, raw units. 0n on
+     * fallback path or when handler couldn't quote.
+     */
+    feeAmountInput: bigint;
+    /** V4 Quoter's gas estimate for the route. */
+    gasEstimate: bigint;
+    quoteError?: ApiQuoteError;
+}
+interface ApiSwapExactOutRequest {
+    chainId: number;
+    userAddress: Address;
+    inputTokenAddress: Address;
+    outputTokenAddress: Address;
+    /** Exact OUTPUT token amount the user wants (raw decimals). */
+    amount: bigint;
+    /** ERC-4337 account nonce for the user's EOA (from EntryPoint). */
+    aaNonce: bigint;
+    /**
+     * Slippage tolerance in basis points (1 bps = 0.01%). Default: 50
+     * for single-hop, 100 for multi-hop. Slippage caps `maxAmountIn`
+     * upward (ceiling division) — the user agrees to spend up to this
+     * much extra to lock in the exact output.
+     */
+    slippageBps?: number;
+    /** Pools to consider. */
+    pools?: PoolKey[];
+    /**
+     * Operator fee in INPUT token units, paid to PAFI fee recipient
+     * BEFORE the swap. Charged input-side because exact-output promises
+     * the user a precise output amount.
+     *
+     * - `undefined` (default): handler auto-quotes via the operator-fee
+     *   helper appropriate to `inputTokenAddress` (USDT/USDC/PT).
+     * - `0n`: strip the fee transfer (unsponsored fallback path).
+     * - explicit `bigint`: override.
+     */
+    gasFeeAmountInput?: bigint;
+}
+interface ApiSwapExactOutResponse {
+    /** Unsigned UserOp — attach paymaster + user signature, submit to Bundler. */
+    userOp: PartialUserOperation;
+    /**
+     * Fee-stripped fallback variant. Emitted only when `gasFeeAmountInput > 0`.
+     * Submit when the paymaster refuses sponsorship.
+     */
+    userOpFallback?: PartialUserOperation;
+    /** Echoes `request.amount` — the exact output. */
+    outputAmount: bigint;
+    /** Raw input amount from the V4 quoter, before slippage. For display. */
+    estimatedInputAmount: bigint;
+    /** Maximum input accepted — encoded in the UserOp calldata. */
+    maxAmountIn: bigint;
+    /** Number of hops in the chosen route. */
+    hops: number;
+    /** Swap deadline (unix seconds). */
+    deadline: bigint;
+    /**
+     * Operator fee amount embedded — echoes auto-quote or override.
+     * Denominated in the INPUT token. `0n` when no-fee mode.
+     */
+    feeAmountUsed: bigint;
+    feeRecipient: Address;
+}
 interface ApiPerpDepositRequest {
     chainId: number;
     userAddress: Address;
@@ -253,12 +342,41 @@ declare class TradingHandlers {
      * net. Quote response surfaces both `estimatedOutputAmount` (gross)
      * and `outputNet` so the FE can display reality.
      *
-     * v0.3.1 — `authenticatedAddress` first param. Caller (issuer
-     * controller / FE proxy) MUST pass the address extracted from the
-     * verified session/JWT. Handler asserts it equals
-     * `request.userAddress`. See SDK_CORE_TRADING_AUDIT.md C6.
+     * `authenticatedAddress` first param: caller (issuer controller / FE
+     * proxy) MUST pass the address extracted from the verified
+     * session/JWT. Handler asserts it equals `request.userAddress`.
      */
     handleSwap(authenticatedAddress: Address, request: ApiSwapRequest): Promise<ApiSwapResponse>;
+    /**
+     * Quote the input required to receive `request.amount` of the output
+     * token via Uniswap V4. Input-side operator fee is auto-quoted, so
+     * `inputGross = estimatedInputAmount + feeAmountInput` is the total
+     * the user must hold.
+     *
+     * Returns `quoteError: "QUOTE_UNAVAILABLE"` rather than throwing when
+     * no path exists.
+     */
+    handleQuoteExactOut(request: ApiQuoteExactOutRequest): Promise<ApiQuoteExactOutResponse>;
+    /**
+     * Build a V4 exact-output swap UserOp.
+     *
+     * Quotes the best exact-output route, applies slippage as a CEILING on
+     * `maxAmountIn` (so the cap is never silently tightened by floor
+     * division), then encodes a 4-step batch:
+     *
+     *   inputToken.transfer(feeRecipient, gasFeeAmountInput)  [if > 0]
+     *     → input.approve(Permit2, maxAmountIn)
+     *     → Permit2.approve(router, maxAmountIn)
+     *     → UniversalRouter.execute (V4 SWAP_EXACT_OUT)
+     *
+     * Operator fee is INPUT-token-side (charged before swap) so the user
+     * receives exactly `request.amount` of output.
+     *
+     * `authenticatedAddress` first param: caller MUST pass the address
+     * extracted from the verified session/JWT. Handler asserts equality
+     * with `request.userAddress`.
+     */
+    handleSwapExactOut(authenticatedAddress: Address, request: ApiSwapExactOutRequest): Promise<ApiSwapExactOutResponse>;
     /**
      * Build an Orderly perp deposit UserOp.
      *
@@ -290,6 +408,8 @@ declare function buildErc20ApprovalCalldata(spender: Address, amount: bigint): H
  */
 declare function buildPermit2ApprovalCalldata(token: Address, spender: Address, amount: bigint, expiration: number): Hex;
 
+declare const SWAP_EXACT_OUT_SINGLE: 8;
+declare const SWAP_EXACT_OUT: 9;
 /**
  * Build the calldata inputs[0] (the V4_SWAP command payload) for
  * UniversalRouter.execute.
@@ -308,22 +428,33 @@ declare function buildUniversalRouterExecuteArgs(currencyIn: Address, path: Path
     inputs: Hex[];
 };
 /**
- * Build UniversalRouter execute args from a quote result.
+ * Build the calldata inputs[0] (the V4_SWAP command payload) for
+ * UniversalRouter.execute, using the V4 exact-output flow.
  *
- * Takes the output of `findBestQuote` / `quoteBestRoute` and produces
- * ready-to-use `{ commands, inputs }` for `UniversalRouter.execute`.
+ * Actions encoded: SWAP_EXACT_OUT → SETTLE_ALL → TAKE_ALL
  *
- * @param quote        - Quote result containing the path
- * @param currencyIn   - Input token address
- * @param currencyOut  - Output token address
- * @param amountIn     - Exact input amount (same value passed to the quoter)
- * @param minAmountOut - Minimum acceptable output (caller applies slippage)
+ * Settle/take semantics flip vs. the exact-input builder:
+ *   - SETTLE_ALL caps the input pulled at `maxAmountIn` (router pulls
+ *     only the actual amount the swap consumed; reverts if it exceeds
+ *     the cap).
+ *   - TAKE_ALL requires the user to receive *exactly* `amountOut` of
+ *     `outputCurrency`.
  *
- * @deprecated Since v1.4 — the Issuer App no longer handles swaps.
- * For the new PT→USDT batch call on PAFI Web (Scenario 4 with
- * EIP-7702 gas deduction), use `buildSwapWithGasDeduction()` (v1.5).
- * This helper is kept for legacy v0.2.x consumers; will be removed in v2.0.
+ * The `path` argument here is in V4 exact-output orientation — i.e.
+ * traversed output→input — which is what `findBestQuoteExactOut`
+ * (and `buildAllPaths(pools, tokenOut, tokenIn, ...)`) returns.
+ *
+ * @throws if `amountOut` or `maxAmountIn` exceeds 2^128 - 1.
+ */
+declare function buildV4SwapInputExactOut(currencyOut: Address, path: PathKey[], amountOut: bigint, maxAmountIn: bigint, inputCurrency: Address): Hex;
+/**
+ * Build the full commands + inputs args for UniversalRouter.execute,
+ * using the V4 exact-output flow.
  */
+declare function buildUniversalRouterExecuteArgsExactOut(currencyOut: Address, path: PathKey[], amountOut: bigint, maxAmountIn: bigint, inputCurrency: Address): {
+    commands: Hex;
+    inputs: Hex[];
+};
 declare function buildSwapFromQuote(params: {
     quote: QuoteResult;
     currencyIn: Address;
@@ -452,6 +583,80 @@ interface BuildSwapUserOpParams {
  *   negative, `swapPath` is empty, or `minAmountOut < gasFeeAmountOutput`.
  */
 declare function buildSwapUserOp(params: BuildSwapUserOpParams): PartialUserOperation;
+/**
+ * Parameters for `buildSwapUserOpExactOut`.
+ *
+ * @remarks
+ * The user must hold **`maxAmountIn + gasFeeAmountInput`** of
+ * `inputTokenAddress` before this UserOp executes — the operator-fee
+ * transfer is pre-swap, so it cannot be paid from swap proceeds.
+ */
+interface BuildSwapUserOpExactOutParams {
+    /** User's EOA (with EIP-7702 delegation to BatchExecutor). */
+    userAddress: Address;
+    /** ERC-4337 account nonce — fetched from EntryPoint by the caller. */
+    aaNonce: bigint;
+    /** Token being spent — approved to Permit2 + UniversalRouter. */
+    inputTokenAddress: Address;
+    /** Token user receives (exactly `amountOut` of). */
+    outputTokenAddress: Address;
+    /** UniversalRouter contract address (chain-specific). */
+    universalRouterAddress: Address;
+    /** Exact OUTPUT token amount the user wants to receive. */
+    amountOut: bigint;
+    /**
+     * Maximum INPUT token amount the user is willing to spend on the swap
+     * (slippage cap). The Permit2 approval covers this amount; the swap
+     * settles only the actual amount consumed.
+     */
+    maxAmountIn: bigint;
+    /**
+     * V4 pool path in **output→input** orientation. Single-hop = 1 PathKey,
+     * multi-hop = N. Get this from `findBestQuoteExactOut().bestRoute.path`.
+     */
+    swapPath: PathKey[];
+    /** Unix seconds. After this, the router rejects the swap. */
+    deadline: bigint;
+    /**
+     * Operator gas-reimbursement fee — paid in INPUT token, transferred
+     * BEFORE the swap. Omitted from the batch when 0n.
+     *
+     * Charged input-side rather than output-side because exact-output
+     * promises the user a precise output amount; deducting from output
+     * would silently break that promise. Mirrors the v0.3 input-side fee
+     * pattern used by perp-deposit.
+     */
+    gasFeeAmountInput: bigint;
+    /**
+     * Where the gas fee lands — typically the canonical PAFI fee
+     * recipient from `getContractAddresses(chainId).pafiFeeRecipient`.
+     */
+    feeRecipient: Address;
+    /** Override ERC-4337 gas estimates. Defaults are conservative. */
+    gasLimits?: {
+        callGasLimit?: bigint;
+        verificationGasLimit?: bigint;
+        preVerificationGas?: bigint;
+    };
+}
+/**
+ * Build an unsigned UserOp for the V4 exact-output swap flow.
+ *
+ * UserOp shape (atomic batch via EIP-7702 BatchExecutor):
+ *
+ *   1. `inputToken.transfer(feeRecipient, gasFeeAmountInput)` — operator
+ *      gas reimbursement, paid in INPUT token (omitted when 0).
+ *   2. `inputToken.approve(Permit2, maxAmountIn)` — cap, not exact.
+ *   3. `Permit2.approve(inputToken, router, maxAmountIn, deadline)` —
+ *      Permit2 authorization to UniversalRouter for up to `maxAmountIn`.
+ *   4. `UniversalRouter.execute(commands, inputs, deadline)` — V4
+ *      exact-output swap; user receives exactly `amountOut`.
+ *
+ * @throws when `amountOut`/`maxAmountIn` are non-positive,
+ *   `gasFeeAmountInput` is negative, `swapPath` is empty, or `deadline`
+ *   is out of Permit2's uint48 range.
+ */
+declare function buildSwapUserOpExactOut(params: BuildSwapUserOpExactOutParams): PartialUserOperation;
 
 /**
  * Combine point-token-specific pools and common pools for a given chain.
@@ -507,5 +712,322 @@ declare function quoteBestRoute(client: PublicClient, quoterAddress: Address, ex
  * @param maxHops        - Maximum number of hops per path (default 3)
  */
 declare function findBestQuote(client: PublicClient, chainId: number, tokenIn: Address, tokenOut: Address, exactAmount: bigint, pools?: PoolKey[], quoterAddress?: Address, maxHops?: number): Promise<BestQuote>;
+/**
+ * Quote V4 exact-output for a multi-hop path.
+ *
+ * @param exactCurrency  - The OUTPUT token (the one the user wants to
+ *                         receive a precise amount of).
+ * @param path           - PathKey[] in output→input orientation. Use
+ *                         `buildAllPaths(pools, tokenOut, tokenIn, ...)`
+ *                         (arguments swapped vs. exact-in) to produce
+ *                         the right shape.
+ * @param exactAmount    - Exact OUTPUT amount the user wants.
+ * @returns `{ amountIn, gasEstimate, path }` — the input amount required
+ *          to receive `exactAmount` of `exactCurrency`.
+ */
+declare function quoteExactOutput(client: PublicClient, quoterAddress: Address, exactCurrency: Address, path: PathKey[], exactAmount: bigint): Promise<ExactOutputQuoteResult>;
+/**
+ * Quote V4 exact-output for a single-hop swap, given an explicit PoolKey
+ * and direction.
+ *
+ * `zeroForOne` semantics are identical to the exact-input variant —
+ * "trade direction" is invariant to the exactness parameter. Only
+ * `exactAmount` flips meaning (here: amount of *output* currency the
+ * user wants to receive).
+ */
+declare function quoteExactOutputSingle(client: PublicClient, quoterAddress: Address, poolKey: PoolKey, zeroForOne: boolean, exactAmount: bigint, hookData: `0x${string}`): Promise<{
+    amountIn: bigint;
+    gasEstimate: bigint;
+}>;
+/**
+ * Try multiple PathKey[] routes for an exact-output swap and return the
+ * route requiring the **smallest** input amount, plus all results.
+ * Routes that fail (e.g. pool does not exist) are silently skipped.
+ *
+ * Uses viem multicall to batch all quotes into a single RPC call.
+ */
+declare function quoteBestRouteExactOut(client: PublicClient, quoterAddress: Address, exactCurrency: Address, routes: PathKey[][], exactAmount: bigint): Promise<ExactOutputBestQuote>;
+/**
+ * Find and quote the best V4 exact-output route from `tokenIn` to
+ * `tokenOut` for a desired output amount.
+ *
+ * Symmetric to `findBestQuote` but with two key differences:
+ *
+ *   - `exactAmount` is denominated in `tokenOut` (the OUTPUT token).
+ *   - Internally calls `buildAllPaths(allPools, tokenOut, tokenIn, ...)`
+ *     (arguments swapped) to enumerate paths in output→input
+ *     orientation, which is what `quoteExactOutput` expects.
+ *
+ * @param client        - viem PublicClient.
+ * @param chainId       - Chain ID (looks up COMMON_POOLS + V4_QUOTER_ADDRESSES).
+ * @param tokenIn       - Input token address (what user pays).
+ * @param tokenOut      - Output token address (what user wants exactly).
+ * @param exactAmount   - Exact OUTPUT amount.
+ * @param pools         - Additional pools (e.g. point-token-specific).
+ * @param quoterAddress - Override the default V4 Quoter address.
+ * @param maxHops       - Maximum number of hops per path (default 3).
+ */
+declare function findBestQuoteExactOut(client: PublicClient, chainId: number, tokenIn: Address, tokenOut: Address, exactAmount: bigint, pools?: PoolKey[], quoterAddress?: Address, maxHops?: number): Promise<ExactOutputBestQuote>;
+
+interface SwapDirectParams {
+    /** User EOA — must be delegated via EIP-7702 to a PAFI-supported impl. */
+    userAddress: Address;
+    chainId: number;
+    inputTokenAddress: Address;
+    outputTokenAddress: Address;
+    /** Input amount (raw token decimals). */
+    amount: bigint;
+    /** Pools to route through. Caller pre-fetches via `fetchPafiPools`. */
+    pools?: PoolKey[];
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    /**
+     * Slippage tolerance in basis points. Default 50 single-hop / 100
+     * multi-hop (handler picks based on `bestRoute.path.length`).
+     */
+    slippageBps?: number;
+    /** Swap deadline (unix seconds). Default = now + 5 minutes. */
+    deadline?: bigint;
+    /**
+     * Operator fee in OUTPUT token, paid to PAFI fee recipient.
+     *
+     * - `undefined` (default for direct path): **skip the fee transfer
+     *   entirely** — PAFI is not sponsoring this swap, no reimbursement
+     *   owed. Most callers want this.
+     * - `0n` — same as above, explicit.
+     * - explicit `bigint` — include the fee transfer (rare; only when
+     *   issuer dev/test wants to mirror sponsored behaviour).
+     */
+    gasFeeAmountOutput?: bigint;
+    /** Wait for receipt before returning. Default `true`. */
+    waitForReceipt?: boolean;
+    onWarning?: (msg: string) => void;
+}
+interface SwapDirectResult {
+    txHash: Hex;
+    receipt?: TransactionReceipt;
+    estimatedOutputAmount: bigint;
+    minAmountOut: bigint;
+    hops: number;
+    deadline: bigint;
+    feeAmountUsed: bigint;
+}
+/**
+ * One-shot helper for the **FE-direct swap** path — no AA, no bundler,
+ * no PAFI sponsor-relayer. The user EOA pays gas in ETH and broadcasts
+ * a single type-2 transaction calling its own EIP-7702 delegated
+ * bytecode (`Simple7702Account.executeBatch`).
+ *
+ * Flow:
+ *   1. Verify the EOA has EIP-7702 delegation to a PAFI-supported impl
+ *      (Simple7702Account or Coinbase SW v2 BatchExecutor). Throw with
+ *      a clear hint pointing at `delegateDirect()` if not delegated.
+ *   2. `findBestQuote` → best route + gross output.
+ *   3. `buildSwapUserOp` → encoded `executeBatch(calls)` calldata.
+ *   4. `walletClient.sendTransaction({ to: userAddress, data: callData })`
+ *      — self-call into the delegated bytecode, which dispatches the
+ *      batch (input.approve → Permit2.approve → UR.execute → optional
+ *      fee transfer).
+ *   5. Wait for receipt (optional).
+ *
+ * Use when:
+ *   - The FE doesn't have a Pimlico API key + doesn't want to depend on
+ *     PAFI sponsor-relayer.
+ *   - The user already has a small ETH balance.
+ *   - You need a deterministic, single-tx swap (vs. AA UserOp's longer
+ *     bundler round-trip).
+ *
+ * Throws when the user is NOT yet delegated — caller should run
+ * `delegateDirect` first or use the AA path (`TradingHandlers.handleSwap`
+ * + `permissionless`).
+ *
+ * @example
+ * ```ts
+ * import { swapDirect, fetchPafiPools } from "@pafi-dev/trading";
+ *
+ * const pools = await fetchPafiPools(8453, POINT_TOKEN);
+ * const result = await swapDirect({
+ *   userAddress: wallet.address,
+ *   chainId: 8453,
+ *   inputTokenAddress: POINT_TOKEN,
+ *   outputTokenAddress: USDT,
+ *   amount: parseUnits("100", 18),
+ *   pools,
+ *   publicClient,
+ *   walletClient,
+ * });
+ * console.log("Swap tx:", result.txHash);
+ * ```
+ */
+declare function swapDirect(params: SwapDirectParams): Promise<SwapDirectResult>;
+
+interface SwapDirectExactOutParams {
+    /** User EOA — must be delegated via EIP-7702 to a PAFI-supported impl. */
+    userAddress: Address;
+    chainId: number;
+    inputTokenAddress: Address;
+    outputTokenAddress: Address;
+    /** Exact OUTPUT amount the user wants to receive (raw token decimals). */
+    amount: bigint;
+    /** Pools to route through. Caller pre-fetches via `fetchPafiPools`. */
+    pools?: PoolKey[];
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    /**
+     * Slippage tolerance in basis points. Default 50 single-hop / 100
+     * multi-hop. Slippage is applied as a CEILING on `maxAmountIn`.
+     */
+    slippageBps?: number;
+    /** Swap deadline (unix seconds). Default = now + 5 minutes. */
+    deadline?: bigint;
+    /**
+     * Operator fee in INPUT token, paid to PAFI fee recipient.
+     *
+     * - `undefined` (default for direct path): **skip the fee transfer
+     *   entirely** — PAFI is not sponsoring this swap, no reimbursement
+     *   owed. Most callers want this.
+     * - `0n` — same as above, explicit.
+     * - explicit `bigint` — include the fee transfer (rare; only when
+     *   issuer dev/test wants to mirror sponsored behaviour).
+     */
+    gasFeeAmountInput?: bigint;
+    /** Wait for receipt before returning. Default `true`. */
+    waitForReceipt?: boolean;
+    onWarning?: (msg: string) => void;
+}
+interface SwapDirectExactOutResult {
+    txHash: Hex;
+    receipt?: TransactionReceipt;
+    /** Echoes `params.amount` — the exact output. */
+    outputAmount: bigint;
+    /** Raw input amount from the V4 quoter, before slippage. */
+    estimatedInputAmount: bigint;
+    /** Slippage-bumped cap on input — encoded in the swap calldata. */
+    maxAmountIn: bigint;
+    hops: number;
+    deadline: bigint;
+    feeAmountUsed: bigint;
+}
+/**
+ * One-shot helper for the **FE-direct exact-output swap** path — no AA,
+ * no bundler, no PAFI sponsor-relayer. Symmetric to `swapDirect` but
+ * specifies the OUTPUT amount and bumps slippage UPWARD on `maxAmountIn`.
+ *
+ * Caller pre-conditions:
+ *
+ *   - User EOA already has EIP-7702 delegation (`delegateDirect` first).
+ *   - User EOA holds **`maxAmountIn + gasFeeAmountInput`** of
+ *     `inputTokenAddress` (not just `amount` — that's output).
+ *
+ * Flow:
+ *   1. Verify the EOA has EIP-7702 delegation to a PAFI-supported impl.
+ *   2. `findBestQuoteExactOut` → best route + required input.
+ *   3. Slippage ceiling → `maxAmountIn`.
+ *   4. `buildSwapUserOpExactOut` → encoded `executeBatch(calls)` calldata.
+ *   5. `walletClient.sendTransaction({ to: userAddress, data: callData })`.
+ *   6. Wait for receipt (optional).
+ *
+ * @example
+ * ```ts
+ * import { swapDirectExactOut, fetchPafiPools } from "@pafi-dev/trading";
+ *
+ * const pools = await fetchPafiPools(8453, POINT_TOKEN);
+ * const result = await swapDirectExactOut({
+ *   userAddress: wallet.address,
+ *   chainId: 8453,
+ *   inputTokenAddress: POINT_TOKEN,
+ *   outputTokenAddress: USDT,
+ *   amount: parseUnits("50", 6), // exactly 50 USDT
+ *   pools,
+ *   publicClient,
+ *   walletClient,
+ * });
+ * console.log("Swap tx:", result.txHash);
+ * ```
+ */
+declare function swapDirectExactOut(params: SwapDirectExactOutParams): Promise<SwapDirectExactOutResult>;
+
+interface PerpDepositDirectParams {
+    /** User EOA — must be EIP-7702 delegated. */
+    userAddress: Address;
+    chainId: number;
+    /** USDC amount to deposit (6-decimal raw units). */
+    amount: bigint;
+    /** Orderly broker — `'orderly' | 'woofi_pro' | 'logx'`. */
+    brokerId: keyof typeof BROKER_HASHES;
+    publicClient: PublicClient;
+    walletClient: WalletClient;
+    /**
+     * Max acceptable USDC fee charged by the Relay (slippage cap on its
+     * USD-pricing of `msg.value`). Default `max(amount * 5%, 2 USDC)` —
+     * matches `TradingHandlers.handlePerpDeposit`.
+     */
+    maxRelayFee?: bigint;
+    /**
+     * Operator fee in USDC (input-token, BEFORE deposit). Same semantics
+     * as `swapDirect.gasFeeAmountOutput`:
+     *
+     * - `undefined` (default for direct path): **skip the fee transfer**
+     *   — PAFI is not sponsoring this deposit.
+     * - explicit `bigint` — include the fee transfer.
+     */
+    gasFeeUsdc?: bigint;
+    /** Wait for receipt before returning. Default `true`. */
+    waitForReceipt?: boolean;
+    onWarning?: (msg: string) => void;
+}
+interface PerpDepositDirectResult {
+    txHash: Hex;
+    receipt?: TransactionReceipt;
+    /** Resolved USDC fee charged by the Relay. */
+    relayTokenFee: bigint;
+    /** Cap applied to the Relay fee (slippage allowance). */
+    maxFee: bigint;
+    /** USDC reaching Orderly Vault after Relay's fee = amount - relayTokenFee. */
+    netDeposit: bigint;
+    /** Operator fee actually included (0n on default direct path). */
+    feeAmountUsed: bigint;
+    accountId: Hex;
+    brokerHash: Hex;
+    usdcAddress: Address;
+    relayAddress: Address;
+}
+/**
+ * One-shot helper for the **FE-direct perp deposit** path — no AA, no
+ * bundler, no PAFI sponsor-relayer. The user EOA pays gas in ETH and
+ * broadcasts a single type-2 transaction calling its own EIP-7702
+ * delegated bytecode (`Simple7702Account.executeBatch`).
+ *
+ * Flow:
+ *   1. Verify EIP-7702 delegation (same precondition as `swapDirect`).
+ *   2. Resolve USDC + verify broker is whitelisted on Orderly Vault.
+ *   3. Quote `Relay.tokenFee` for the deposit; compute `netDeposit`.
+ *   4. `buildPerpDepositViaRelay` → encoded `executeBatch(calls)`
+ *      (USDC.approve(relay) + Relay.deposit + optional fee transfer).
+ *   5. `walletClient.sendTransaction({ to: userAddress, data: callData })`.
+ *   6. Wait for receipt (optional).
+ *
+ * Use when: same conditions as `swapDirect` — FE doesn't have Pimlico
+ * key, doesn't want sponsor-relayer dependency, user has small ETH.
+ *
+ * Throws when the user is NOT yet delegated.
+ *
+ * @example
+ * ```ts
+ * import { perpDepositDirect } from "@pafi-dev/trading";
+ *
+ * const result = await perpDepositDirect({
+ *   userAddress: wallet.address,
+ *   chainId: 8453,
+ *   amount: parseUnits("10", 6), // 10 USDC
+ *   brokerId: "orderly",
+ *   publicClient,
+ *   walletClient,
+ * });
+ * console.log("Deposit tx:", result.txHash);
+ * console.log("Net deposit to Orderly:", result.netDeposit, "USDC raw");
+ * ```
+ */
+declare function perpDepositDirect(params: PerpDepositDirectParams): Promise<PerpDepositDirectResult>;
 
-export { type ApiPerpDepositRequest, type ApiPerpDepositResponse, type ApiQuoteError, type ApiQuoteRequest, type ApiQuoteResponse, type ApiSwapRequest, type ApiSwapResponse, type BuildSwapUserOpParams, type SwapSimulationResult, TradingHandlers, type TradingHandlersConfig, buildAllPaths, buildErc20ApprovalCalldata, buildPermit2ApprovalCalldata, buildSwapFromQuote, buildSwapUserOp, buildUniversalRouterExecuteArgs, buildV4SwapInput, checkAllowance, combineRoutes, findBestQuote, quoteBestRoute, quoteExactInput, quoteExactInputSingle, simulateSwap };
+export { type ApiPerpDepositRequest, type ApiPerpDepositResponse, type ApiQuoteError, type ApiQuoteExactOutRequest, type ApiQuoteExactOutResponse, type ApiQuoteRequest, type ApiQuoteResponse, type ApiSwapExactOutRequest, type ApiSwapExactOutResponse, type ApiSwapRequest, type ApiSwapResponse, type BuildSwapUserOpExactOutParams, type BuildSwapUserOpParams, type PerpDepositDirectParams, type PerpDepositDirectResult, SWAP_EXACT_OUT, SWAP_EXACT_OUT_SINGLE, type SwapDirectExactOutParams, type SwapDirectExactOutResult, type SwapDirectParams, type SwapDirectResult, type SwapSimulationResult, TradingHandlers, type TradingHandlersConfig, buildAllPaths, buildErc20ApprovalCalldata, buildPermit2ApprovalCalldata, buildSwapFromQuote, buildSwapUserOp, buildSwapUserOpExactOut, buildUniversalRouterExecuteArgs, buildUniversalRouterExecuteArgsExactOut, buildV4SwapInput, buildV4SwapInputExactOut, checkAllowance, combineRoutes, findBestQuote, findBestQuoteExactOut, perpDepositDirect, quoteBestRoute, quoteBestRouteExactOut, quoteExactInput, quoteExactInputSingle, quoteExactOutput, quoteExactOutputSingle, simulateSwap, swapDirect, swapDirectExactOut };