@b3dotfun/sdk 0.1.65 → 0.1.66-alpha.0

package/src/anyspend/llms.txt

@@ -0,0 +1,185 @@
+# AnySpend SDK
+
+> Accept crypto payments and onboard users with zero friction. Users pay with any token on any chain in one seamless experience.
+
+## Overview
+
+AnySpend is a payment SDK (`@b3dotfun/sdk`) for crypto payments and fiat onramps. It provides React components, hooks, and service methods for token swaps, cross-chain transactions, NFT purchases, and merchant checkout flows.
+
+Supported networks: Ethereum, Base, B3.
+Supported platforms: React Web (full), React Native (hooks + services only), Node.js (services only).
+
+## Installation
+
+```bash
+npm install @b3dotfun/sdk
+```
+
+Wrap your app with the provider:
+
+```tsx
+import { AnySpendProvider } from "@b3dotfun/sdk/anyspend/react";
+import "@b3dotfun/sdk/index.css";
+
+function App() {
+  return <AnySpendProvider>{/* app */}</AnySpendProvider>;
+}
+```
+
+Requires Node.js v20.15.0+, React 18/19.
+
+## Components
+
+### AnySpend
+
+Primary swap/onramp interface. Supports modal or page mode.
+
+Props: `mode` ("modal"|"page"), `defaultActiveTab` ("crypto"|"fiat"), `destinationTokenAddress`, `destinationTokenChainId`, `recipientAddress`, `hideTransactionHistoryButton`, `loadOrder`, `onSuccess`, `checkoutSession`.
+
+```tsx
+<AnySpend
+  mode="page"
+  defaultActiveTab="crypto"
+  recipientAddress="0x..."
+  onSuccess={(txHash) => console.log(txHash)}
+/>
+```
+
+### AnySpendNFTButton
+
+One-click NFT purchase button.
+
+Props: `nftContract` (NFTContract), `recipientAddress`, `onSuccess`.
+
+NFTContract shape: `{ chainId, contractAddress, price (wei), priceFormatted, currency: { chainId, address, name, symbol, decimals }, name, description, imageUrl }`.
+
+### AnySpendCustom
+
+Flexible component for custom smart contract interactions (staking, gaming, DeFi).
+
+Props: `orderType` ("custom"), `dstChainId`, `dstToken`, `dstAmount`, `contractAddress`, `encodedData`, `spenderAddress`, `metadata`, `header`, `onSuccess`, `checkoutSession`.
+
+### AnySpendCustomExactIn
+
+Like AnySpendCustom but for exact-input flows. Also supports `checkoutSession` prop.
+
+### Specialized Components
+
+- `AnySpendNFT` — Enhanced NFT with marketplace features
+- `AnySpendStakeB3` — B3 token staking
+- `AnySpendBuySpin` — Gaming spin wheel purchases
+- `AnySpendTournament` — Tournament entry payments
+
+## Hooks
+
+### useAnyspendQuote(quoteRequest)
+
+Get real-time pricing. QuoteRequest: `{ srcChain, dstChain, srcTokenAddress, dstTokenAddress, type ("swap"|"custom"), tradeType ("EXACT_INPUT"|"EXACT_OUTPUT"), amount }`.
+
+Returns: `{ anyspendQuote, isLoadingAnyspendQuote, getAnyspendQuoteError, refetchAnyspendQuote }`.
+
+### useAnyspendCreateOrder(options)
+
+Create orders. Options: `{ onSuccess, onError, onSettled }`.
+
+Returns: `{ createOrder(request), isCreatingOrder, createOrderError }`.
+
+### useAnyspendOrderAndTransactions(orderId)
+
+Monitor order status and transactions in real-time.
+
+Returns: `{ orderAndTransactions: { order, depositTxs, relayTx, executeTx, refundTxs }, isLoadingOrderAndTransactions, getOrderAndTransactionsError }`.
+
+### useAnyspendOrderHistory(creatorAddress, limit, offset)
+
+Paginated order history for a user.
+
+### useAnyspendTokens(chainId, search)
+
+Get available tokens for a chain.
+
+### useCoinbaseOnrampOptions()
+
+Get Coinbase onramp config for fiat payments.
+
+### useStripeClientSecret(orderData)
+
+Get Stripe payment intent for card payments.
+
+### useCreateCheckoutSession()
+
+Mutation hook for creating checkout sessions.
+
+Returns: `{ mutate: createSession, data, isPending }`.
+
+### useCheckoutSession(sessionId)
+
+Query hook that auto-polls a checkout session. Stops on `complete` or `expired`.
+
+Returns: `{ data: session, isLoading }`.
+
+## Checkout Sessions
+
+Stripe-like checkout sessions decoupled from orders. Merchants create a session first, then create an order when the user picks a payment method.
+
+### Flow
+
+1. `POST /checkout-sessions` → Creates session (DB only, instant). Returns `{ id, status: "open" }`.
+2. `POST /orders` with `checkoutSessionId` → Creates order linked to session. Returns order with `globalAddress` or `oneClickBuyUrl`.
+3. User pays (crypto to globalAddress, or onramp redirect).
+4. `GET /checkout-sessions/:id` → Poll status. Returns `{ status: "complete", order_id }`.
+
+### Session Statuses
+
+`open` → `processing` → `complete`, or `open` → `expired`.
+
+### API Endpoints
+
+**POST /checkout-sessions** — Create session. All fields optional: `success_url`, `cancel_url`, `metadata`, `client_reference_id`, `expires_in`.
+
+**POST /orders** — Standard order creation. Add `checkoutSessionId` to link. Validates: session exists (400), session is open (400), session has no order yet (409).
+
+**GET /checkout-sessions/:id** — Retrieve session. Query `?include=order` to embed full order with transactions.
+
+**POST /checkout-sessions/:id/expire** — Manually expire an open session.
+
+### Redirect URL Templates
+
+`success_url` and `cancel_url` support `{SESSION_ID}` and `{ORDER_ID}` template variables. If no variable present, `?sessionId=<uuid>` is appended.
+
+### Component Integration
+
+Pass `checkoutSession` prop to `AnySpend`, `AnySpendCustom`, or `AnySpendCustomExactIn`:
+
+```tsx
+<AnySpend
+  checkoutSession={{
+    success_url: "https://myshop.com/success?session={SESSION_ID}",
+    cancel_url: "https://myshop.com/cancel",
+    metadata: { sku: "widget-1" },
+  }}
+/>
+```
+
+Without the prop, all existing flows are unchanged.
+
+## Order Status Lifecycle
+
+`scanning_deposit_transaction` → `obtain_token` → `sending_token_from_vault` → `relay` → `executed`
+
+Failure states: `obtain_failed`, `expired`, `refunding`, `refunded`, `failure`.
+
+For Stripe: `waiting_stripe_payment` precedes processing.
+
+## Error Codes
+
+Payment: `INSUFFICIENT_BALANCE`, `INVALID_TOKEN_ADDRESS`, `MINIMUM_AMOUNT_NOT_MET`, `MAXIMUM_AMOUNT_EXCEEDED`.
+Network: `SLIPPAGE`, `NETWORK_ERROR`, `QUOTE_EXPIRED`, `CHAIN_NOT_SUPPORTED`.
+Contract: `CONTRACT_CALL_FAILED`, `INSUFFICIENT_GAS`, `NONCE_TOO_LOW`, `TRANSACTION_REVERTED`.
+
+## Links
+
+- Docs: docs/installation.md, docs/components.md, docs/hooks.md, docs/examples.md, docs/checkout-sessions.md, docs/error-handling.md
+- Live demo: https://anyspend.com
+- Discord: https://discord.gg/b3dotfun
+- Issues: https://github.com/b3-fun/b3/issues

package/src/anyspend/react/components/AnySpend.tsx

@@ -52,6 +52,7 @@ import { useAutoSelectCryptoPaymentMethod } from "../hooks/useAutoSelectCryptoPa
 import { useConnectedWalletDisplay } from "../hooks/useConnectedWalletDisplay";
 import { useCryptoPaymentMethodState } from "../hooks/useCryptoPaymentMethodState";
 import { useDirectTransfer } from "../hooks/useDirectTransfer";
+import { useOnOrderSuccess } from "../hooks/useOnOrderSuccess";
 import { useRecipientAddressState } from "../hooks/useRecipientAddressState";
 import { AnySpendFingerprintWrapper, getFingerprintConfig } from "./AnySpendFingerprintWrapper";
 import { CryptoPaymentMethod, CryptoPaymentMethodType } from "./common/CryptoPaymentMethod";
@@ -126,6 +127,8 @@ export function AnySpend(props: {
   allowDirectTransfer?: boolean;
   /** Fixed destination token amount (in wei/smallest unit). When provided, user cannot change the amount. */
   destinationTokenAmount?: string;
+  /** Opaque metadata passed to the order for callbacks (e.g., workflow form data) */
+  callbackMetadata?: Record<string, unknown>;
 }) {
   const fingerprintConfig = getFingerprintConfig();
 
@@ -158,6 +161,7 @@ function AnySpendInner({
   classes,
   allowDirectTransfer = false,
   destinationTokenAmount,
+  callbackMetadata,
 }: {
   sourceChainId?: number;
   destinationTokenAddress?: string;
@@ -179,6 +183,7 @@ function AnySpendInner({
   classes?: AnySpendClasses;
   allowDirectTransfer?: boolean;
   destinationTokenAmount?: string;
+  callbackMetadata?: Record<string, unknown>;
 }) {
   const searchParams = useSearchParamsSSR();
   const router = useRouter();
@@ -208,9 +213,6 @@ function AnySpendInner({
     toAmount?: string;
   } | null>(null);
 
-  // Track if onSuccess has been called for the current order
-  const onSuccessCalled = useRef(false);
-
   // Track animation direction for TransitionPanel
   const animationDirection = useRef<"forward" | "back" | null>(null);
   // Track previous panel for proper back navigation
@@ -704,19 +706,8 @@ function AnySpendInner({
     }
   }, [anyspendQuote, isSrcInputDirty, destinationTokenAmount]);
 
-  useEffect(() => {
-    if (oat?.data?.order.status === "executed" && !onSuccessCalled.current) {
-      console.log("Calling onSuccess");
-      const txHash = oat?.data?.executeTx?.txHash;
-      onSuccess?.(txHash);
-      onSuccessCalled.current = true;
-    }
-  }, [oat?.data?.order.status, oat?.data?.executeTx?.txHash, onSuccess]);
-
-  // Reset flag when orderId changes
-  useEffect(() => {
-    onSuccessCalled.current = false;
-  }, [orderId]);
+  // Call onSuccess when order is executed
+  useOnOrderSuccess({ orderData: oat, orderId, onSuccess });
 
   const { createOrder, isCreatingOrder } = useAnyspendCreateOrder({
     onSuccess: data => {
@@ -979,6 +970,7 @@ function AnySpendInner({
         srcAmount: srcAmountBigInt.toString(),
         expectedDstAmount: anyspendQuote?.data?.currencyOut?.amount || "0",
         creatorAddress: globalAddress,
+        callbackMetadata,
       });
     } catch (err: any) {
       console.error(err);
@@ -1056,6 +1048,7 @@ function AnySpendInner({
         },
         expectedDstAmount: anyspendQuote?.data?.currencyOut?.amount?.toString() || "0",
         creatorAddress: globalAddress,
+        callbackMetadata,
       });
     } catch (err: any) {
       console.error(err);
@@ -1227,7 +1220,6 @@ function AnySpendInner({
               anyspendQuote={anyspendQuote}
               onTokenSelect={onTokenSelect}
               onShowFeeDetail={() => navigateToPanel(PanelView.FEE_DETAIL, "forward")}
-              skipAutoMaxOnTokenChange={!!destinationTokenAmount}
             />
           ) : (
             <motion.div

package/src/anyspend/react/components/AnySpendCollectorClubPurchase.tsx

@@ -27,28 +27,28 @@
 import { USDC_BASE } from "@b3dotfun/sdk/anyspend/constants";
 import { components } from "@b3dotfun/sdk/anyspend/types/api";
 import { GetQuoteResponse } from "@b3dotfun/sdk/anyspend/types/api_req_res";
+import { PUBLIC_BASE_RPC_URL } from "@b3dotfun/sdk/shared/constants";
 import { formatUnits } from "@b3dotfun/sdk/shared/utils/number";
-import React, { useMemo } from "react";
-import { encodeFunctionData } from "viem";
+import React, { useEffect, useMemo, useState } from "react";
+import { createPublicClient, encodeFunctionData, http } from "viem";
+import { base } from "viem/chains";
 import { AnySpendCustom } from "./AnySpendCustom";
+import {
+  BUY_PACKS_FOR_ABI,
+  BUY_PACKS_FOR_WITH_DISCOUNT_ABI,
+  GET_DISCOUNT_CODE_ABI,
+  IS_DISCOUNT_CODE_VALID_FOR_PACK_ABI,
+} from "./ccShopAbi";
 
 // Collector Club Shop contract addresses on Base
 const CC_SHOP_ADDRESS = "0x47366E64E4917dd4DdC04Fb9DC507c1dD2b87294";
 const CC_SHOP_ADDRESS_STAGING = "0x8b751143342ac41eB965E55430e3F7Adf6BE01fA";
 const BASE_CHAIN_ID = 8453;
 
-// ABI for buyPacksFor function only
-const BUY_PACKS_FOR_ABI = {
-  inputs: [
-    { internalType: "address", name: "user", type: "address" },
-    { internalType: "uint256", name: "packId", type: "uint256" },
-    { internalType: "uint256", name: "amount", type: "uint256" },
-  ],
-  name: "buyPacksFor",
-  outputs: [],
-  stateMutability: "nonpayable",
-  type: "function",
-} as const;
+const basePublicClient = createPublicClient({
+  chain: base,
+  transport: http(PUBLIC_BASE_RPC_URL),
+});
 
 export interface AnySpendCollectorClubPurchaseProps {
   /**
@@ -118,6 +118,11 @@ export interface AnySpendCollectorClubPurchaseProps {
    * Force fiat payment
    */
   forceFiatPayment?: boolean;
+  /**
+   * Optional discount code to apply to the purchase.
+   * When provided, validates on-chain and adjusts the price accordingly.
+   */
+  discountCode?: string;
 }
 
 export function AnySpendCollectorClubPurchase({
@@ -137,6 +142,7 @@ export function AnySpendCollectorClubPurchase({
   vendingMachineId,
   packType,
   forceFiatPayment,
+  discountCode,
 }: AnySpendCollectorClubPurchaseProps) {
   const ccShopAddress = isStaging ? CC_SHOP_ADDRESS_STAGING : CC_SHOP_ADDRESS;
 
@@ -150,25 +156,159 @@ export function AnySpendCollectorClubPurchase({
     }
   }, [pricePerPack, packAmount]);
 
-  // Calculate fiat amount (totalAmount in USD, assuming USDC with 6 decimals)
+  // Discount code validation state
+  const [discountInfo, setDiscountInfo] = useState<{
+    isValid: boolean;
+    discountAmount: bigint;
+    minPurchaseAmount: bigint;
+    isLoading: boolean;
+    error: string | null;
+  }>({
+    isValid: false,
+    discountAmount: BigInt(0),
+    minPurchaseAmount: BigInt(0),
+    isLoading: false,
+    error: null,
+  });
+
+  // Validate discount code on-chain when provided
+  useEffect(() => {
+    if (!discountCode) {
+      setDiscountInfo({
+        isValid: false,
+        discountAmount: BigInt(0),
+        minPurchaseAmount: BigInt(0),
+        isLoading: false,
+        error: null,
+      });
+      return;
+    }
+
+    let cancelled = false;
+
+    const validateDiscount = async () => {
+      setDiscountInfo(prev => ({ ...prev, isLoading: true, error: null }));
+
+      try {
+        // Validate against specific pack and fetch full details in parallel
+        const [validForPack, codeDetails] = await Promise.all([
+          basePublicClient.readContract({
+            address: ccShopAddress as `0x${string}`,
+            abi: [IS_DISCOUNT_CODE_VALID_FOR_PACK_ABI],
+            functionName: "isDiscountCodeValidForPack",
+            args: [discountCode, BigInt(packId)],
+          }),
+          basePublicClient.readContract({
+            address: ccShopAddress as `0x${string}`,
+            abi: [GET_DISCOUNT_CODE_ABI],
+            functionName: "getDiscountCode",
+            args: [discountCode],
+          }),
+        ]);
+
+        if (cancelled) return;
+
+        const [isValid, discountAmount] = validForPack;
+        const { minPurchaseAmount, packId: restrictedPackId, exists } = codeDetails;
+
+        if (!exists) {
+          setDiscountInfo({
+            isValid: false,
+            discountAmount: BigInt(0),
+            minPurchaseAmount: BigInt(0),
+            isLoading: false,
+            error: "Discount code does not exist",
+          });
+          return;
+        }
+
+        if (!isValid) {
+          // Provide specific error based on code details
+          if (restrictedPackId !== BigInt(0) && restrictedPackId !== BigInt(packId)) {
+            setDiscountInfo({
+              isValid: false,
+              discountAmount: BigInt(0),
+              minPurchaseAmount: BigInt(0),
+              isLoading: false,
+              error: "Discount code is not valid for this pack",
+            });
+          } else {
+            setDiscountInfo({
+              isValid: false,
+              discountAmount: BigInt(0),
+              minPurchaseAmount: BigInt(0),
+              isLoading: false,
+              error: "Invalid or expired discount code",
+            });
+          }
+          return;
+        }
+
+        setDiscountInfo({ isValid: true, discountAmount, minPurchaseAmount, isLoading: false, error: null });
+      } catch (error) {
+        if (cancelled) return;
+        console.error("Failed to validate discount code", { discountCode, error });
+        setDiscountInfo({
+          isValid: false,
+          discountAmount: BigInt(0),
+          minPurchaseAmount: BigInt(0),
+          isLoading: false,
+          error: "Failed to validate discount code",
+        });
+      }
+    };
+
+    validateDiscount();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [discountCode, ccShopAddress, packId]);
+
+  // Calculate effective dstAmount after discount
+  const effectiveDstAmount = useMemo(() => {
+    if (!discountCode || !discountInfo.isValid || discountInfo.discountAmount === BigInt(0)) {
+      return totalAmount;
+    }
+
+    const total = BigInt(totalAmount);
+    const discount = discountInfo.discountAmount;
+
+    if (discount >= total) {
+      console.error("Discount exceeds total price", { totalAmount, discountAmount: discount.toString() });
+      return "0";
+    }
+
+    return (total - discount).toString();
+  }, [totalAmount, discountCode, discountInfo.isValid, discountInfo.discountAmount]);
+
+  // Calculate fiat amount (effectiveDstAmount in USD, assuming USDC with 6 decimals)
   const srcFiatAmount = useMemo(() => {
-    if (!totalAmount || totalAmount === "0") return "0";
-    return formatUnits(totalAmount, USDC_BASE.decimals);
-  }, [totalAmount]);
+    if (!effectiveDstAmount || effectiveDstAmount === "0") return "0";
+    return formatUnits(effectiveDstAmount, USDC_BASE.decimals);
+  }, [effectiveDstAmount]);
 
-  // Encode the buyPacksFor function call
+  // Encode the contract function call (with or without discount)
   const encodedData = useMemo(() => {
     try {
+      if (discountCode && discountInfo.isValid) {
+        return encodeFunctionData({
+          abi: [BUY_PACKS_FOR_WITH_DISCOUNT_ABI],
+          functionName: "buyPacksForWithDiscount",
+          args: [recipientAddress as `0x${string}`, BigInt(packId), BigInt(packAmount), discountCode],
+        });
+      }
+
       return encodeFunctionData({
         abi: [BUY_PACKS_FOR_ABI],
         functionName: "buyPacksFor",
         args: [recipientAddress as `0x${string}`, BigInt(packId), BigInt(packAmount)],
       });
     } catch (error) {
-      console.error("Failed to encode function data", { recipientAddress, packId, packAmount, error });
+      console.error("Failed to encode function data", { recipientAddress, packId, packAmount, discountCode, error });
       return "0x";
     }
-  }, [recipientAddress, packId, packAmount]);
+  }, [recipientAddress, packId, packAmount, discountCode, discountInfo.isValid]);
 
   // Default header if not provided
   const defaultHeader = () => (
@@ -182,6 +322,47 @@ export function AnySpendCollectorClubPurchase({
     </div>
   );
 
+  // Don't render AnySpendCustom while discount is being validated (avoids showing wrong price)
+  if (discountCode && discountInfo.isLoading) {
+    return (
+      <div className="mb-4 flex flex-col items-center gap-3 text-center">
+        <p className="text-as-secondary text-sm">Validating discount code...</p>
+      </div>
+    );
+  }
+
+  if (discountCode && discountInfo.error) {
+    return (
+      <div className="mb-4 flex flex-col items-center gap-3 text-center">
+        <p className="text-sm text-red-500">{discountInfo.error}</p>
+      </div>
+    );
+  }
+
+  if (
+    discountCode &&
+    discountInfo.isValid &&
+    discountInfo.minPurchaseAmount > BigInt(0) &&
+    BigInt(packAmount) < discountInfo.minPurchaseAmount
+  ) {
+    return (
+      <div className="mb-4 flex flex-col items-center gap-3 text-center">
+        <p className="text-sm text-red-500">
+          Minimum purchase of {discountInfo.minPurchaseAmount.toString()} pack
+          {discountInfo.minPurchaseAmount > BigInt(1) ? "s" : ""} required for this discount code
+        </p>
+      </div>
+    );
+  }
+
+  if (discountCode && discountInfo.isValid && effectiveDstAmount === "0") {
+    return (
+      <div className="mb-4 flex flex-col items-center gap-3 text-center">
+        <p className="text-sm text-red-500">Discount exceeds total price</p>
+      </div>
+    );
+  }
+
   return (
     <AnySpendCustom
       loadOrder={loadOrder}
@@ -192,7 +373,7 @@ export function AnySpendCollectorClubPurchase({
       orderType="custom"
       dstChainId={BASE_CHAIN_ID}
       dstToken={paymentToken}
-      dstAmount={totalAmount}
+      dstAmount={effectiveDstAmount}
       contractAddress={ccShopAddress}
       encodedData={encodedData}
       metadata={{
@@ -201,6 +382,9 @@ export function AnySpendCollectorClubPurchase({
         pricePerPack,
         vendingMachineId,
         packType,
+        ...(discountCode && discountInfo.isValid
+          ? { discountCode, discountAmount: discountInfo.discountAmount.toString() }
+          : {}),
       }}
       header={header || defaultHeader}
       onSuccess={onSuccess}

package/src/anyspend/react/components/AnySpendCustom.tsx

@@ -45,6 +45,7 @@ import React, { useCallback, useEffect, useMemo, useState } from "react";
 
 import { base } from "viem/chains";
 import { useCryptoPaymentMethodState } from "../hooks/useCryptoPaymentMethodState";
+import { useOnOrderSuccess } from "../hooks/useOnOrderSuccess";
 import { useRecipientAddressState } from "../hooks/useRecipientAddressState";
 import { AnySpendFingerprintWrapper, getFingerprintConfig } from "./AnySpendFingerprintWrapper";
 import { CryptoPaymentMethod, CryptoPaymentMethodType } from "./common/CryptoPaymentMethod";
@@ -274,9 +275,6 @@ function AnySpendCustomInner({
 
   const [orderId, setOrderId] = useState<string | undefined>(loadOrder);
 
-  // Track if onSuccess has been called for the current order
-  const onSuccessCalled = React.useRef(false);
-
   const [srcChainId, setSrcChainId] = useState<number>(base.id);
 
   // Get token list for token balance check
@@ -433,21 +431,8 @@ function AnySpendCustomInner({
   const { geoData, isOnrampSupported, coinbaseAvailablePaymentMethods, stripeOnrampSupport, stripeWeb2Support } =
     useGeoOnrampOptions(srcFiatAmountForGeoCheck);
 
-  useEffect(() => {
-    if (oat?.data?.order.status === "executed" && !onSuccessCalled.current) {
-      console.log("Calling onSuccess");
-      const relayTxs = oat?.data?.relayTxs;
-      const lastRelayTxHash = relayTxs?.[relayTxs.length - 1]?.txHash;
-      const txHash = oat?.data?.executeTx?.txHash || lastRelayTxHash;
-      onSuccess?.(txHash);
-      onSuccessCalled.current = true;
-    }
-  }, [oat?.data?.order.status, oat?.data?.executeTx?.txHash, oat?.data?.relayTxs, onSuccess]);
-
-  // Reset flag when orderId changes
-  useEffect(() => {
-    onSuccessCalled.current = false;
-  }, [orderId]);
+  // Call onSuccess when order is executed
+  useOnOrderSuccess({ orderData: oat, orderId, onSuccess });
 
   const { createOrder: createRegularOrder, isCreatingOrder: isCreatingRegularOrder } = useAnyspendCreateOrder({
     onSuccess: data => {

package/src/anyspend/react/components/AnySpendCustomExactIn.tsx

@@ -83,6 +83,8 @@ export interface AnySpendCustomExactInProps {
   classes?: AnySpendCustomExactInClasses;
   /** When true, allows direct transfer without swap if source and destination token/chain are the same */
   allowDirectTransfer?: boolean;
+  /** Opaque metadata passed to the order for callbacks (e.g., workflow form data) */
+  callbackMetadata?: Record<string, unknown>;
 }
 
 export function AnySpendCustomExactIn(props: AnySpendCustomExactInProps) {
@@ -120,6 +122,7 @@ function AnySpendCustomExactInInner({
   returnHomeLabel,
   classes,
   allowDirectTransfer = false,
+  callbackMetadata,
 }: AnySpendCustomExactInProps) {
   const actionLabel = customExactInConfig?.action ?? "Custom Execution";
   const setB3ModalOpen = useModalStore(state => state.setB3ModalOpen);
@@ -418,7 +421,6 @@ function AnySpendCustomExactInInner({
               onSelectCryptoPaymentMethod={() => setActivePanel(PanelView.CRYPTO_PAYMENT_METHOD)}
               anyspendQuote={anyspendQuote}
               onTokenSelect={onTokenSelect}
-              skipAutoMaxOnTokenChange={!!destinationTokenAmount}
             />
           ) : (
             <motion.div
@@ -587,6 +589,7 @@ function AnySpendCustomExactInInner({
               ? normalizeAddress(customExactInConfig.spenderAddress)
               : undefined,
           },
+          callbackMetadata,
         });
       } else {
         // EXACT_INPUT mode: create custom_exact_in order (original behavior)
@@ -604,6 +607,7 @@ function AnySpendCustomExactInInner({
           expectedDstAmount: expectedDstAmountRaw,
           creatorAddress: globalAddress,
           payload,
+          callbackMetadata,
         });
       }
     } catch (err: any) {

package/src/anyspend/react/components/AnySpendDeposit.tsx

@@ -123,6 +123,8 @@ export interface AnySpendDepositProps {
   allowDirectTransfer?: boolean;
   /** Fixed destination token amount (in wei/smallest unit). When provided, user cannot change the amount. */
   destinationTokenAmount?: string;
+  /** Opaque metadata passed to the order for callbacks (e.g., workflow form data) */
+  callbackMetadata?: Record<string, unknown>;
 }
 
 // Default supported chains
@@ -248,6 +250,7 @@ export function AnySpendDeposit({
   classes,
   allowDirectTransfer = false,
   destinationTokenAmount,
+  callbackMetadata,
 }: AnySpendDepositProps) {
   // Extract deposit-specific classes for convenience
   const depositClasses = classes?.deposit;
@@ -697,6 +700,7 @@ export function AnySpendDeposit({
             classes={classes?.customExactIn}
             allowDirectTransfer={allowDirectTransfer}
             destinationTokenAmount={destinationTokenAmount}
+            callbackMetadata={callbackMetadata}
           />
         ) : (
           <AnySpend
@@ -720,6 +724,7 @@ export function AnySpendDeposit({
             classes={classes?.anySpend}
             allowDirectTransfer={allowDirectTransfer}
             destinationTokenAmount={destinationTokenAmount}
+            callbackMetadata={callbackMetadata}
           />
         )}
       </div>