@b3dotfun/sdk 0.1.65-alpha.5 → 0.1.65-alpha.7

package/dist/esm/anyspend/react/components/common/OrderTokenAmount.d.ts

@@ -1,5 +1,5 @@
 import { components } from "../../../../anyspend/types/api";
-export declare function OrderTokenAmount({ disabled, inputValue, onChangeInput, context, address, chainId, setChainId, token, setToken, hideTokenSelect, canEditAmount, className, innerClassName, amountClassName, tokenSelectClassName, onTokenSelect, walletAddress, skipAutoMaxOnTokenChange, }: {
+export declare function OrderTokenAmount({ disabled, inputValue, onChangeInput, context, address, chainId, setChainId, token, setToken, hideTokenSelect, canEditAmount, className, innerClassName, amountClassName, tokenSelectClassName, onTokenSelect, }: {
     disabled?: boolean;
     inputValue: string;
     onChangeInput: (value: string) => void;
@@ -18,7 +18,4 @@ export declare function OrderTokenAmount({ disabled, inputValue, onChangeInput,
     onTokenSelect?: (token: components["schemas"]["Token"], event: {
         preventDefault: () => void;
     }) => void;
-    walletAddress?: string | undefined;
-    /** When true, skip auto-setting max balance when token changes (used for fixed destination amount mode) */
-    skipAutoMaxOnTokenChange?: boolean;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/esm/anyspend/react/components/common/OrderTokenAmount.js

@@ -1,63 +1,13 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ChevronsUpDown } from "lucide-react";
-import { useEffect, useRef } from "react";
 import { NumericFormat } from "react-number-format";
-import { formatUnits } from "viem";
 import { ALL_CHAINS, RELAY_SOLANA_MAINNET_CHAIN_ID, getAvailableChainIds } from "../../../../anyspend/index.js";
-import { getNativeRequired } from "../../../../anyspend/utils/chain.js";
-import { isNativeToken } from "../../../../anyspend/utils/token.js";
-import { Button, useTokenBalance } from "../../../../global-account/react/index.js";
+import { Button } from "../../../../global-account/react/index.js";
 import { cn } from "../../../../shared/utils/index.js";
 import { TokenSelector } from "@relayprotocol/relay-kit-ui";
 import { ChainTokenIcon } from "./ChainTokenIcon.js";
-export function OrderTokenAmount({ disabled, inputValue, onChangeInput, context, address, chainId, setChainId, token, setToken, hideTokenSelect = false, canEditAmount = true, className, innerClassName, amountClassName, tokenSelectClassName, onTokenSelect, walletAddress, skipAutoMaxOnTokenChange = false, }) {
-    // Track previous token to detect changes
-    const prevTokenRef = useRef(token.address);
-    // Only get token balance when context is "from" (for setting max amount)
-    const { rawBalance } = useTokenBalance({
-        token,
-        address: context === "from" && walletAddress ? walletAddress : undefined,
-    });
-    useEffect(() => {
-        // Only handle "from" context
-        if (context !== "from")
-            return;
-        // Skip auto-max when in fixed destination amount mode
-        if (skipAutoMaxOnTokenChange) {
-            prevTokenRef.current = token.address;
-            return;
-        }
-        // Check if token changed or if this is the initial load with balance
-        const isTokenChanged = prevTokenRef.current !== token.address;
-        if (isTokenChanged && rawBalance) {
-            console.log(`Setting max balance - Token: ${token.address}, Changed: ${isTokenChanged}`);
-            // Calculate max amount with gas reserve for native tokens
-            let maxAmount;
-            if (isNativeToken(token.address)) {
-                const gasReserve = getNativeRequired(token.chainId);
-                // Ensure we don't go negative
-                maxAmount = rawBalance > gasReserve ? rawBalance - gasReserve : BigInt(0);
-            }
-            else {
-                // For ERC20 tokens, use full balance
-                maxAmount = rawBalance;
-            }
-            // Set the max amount as input value
-            onChangeInput(formatUnits(maxAmount, token.decimals));
-            // Update refs
-            prevTokenRef.current = token.address;
-        }
-    }, [
-        token.address,
-        token.chainId,
-        token.decimals,
-        chainId,
-        context,
-        onChangeInput,
-        rawBalance,
-        skipAutoMaxOnTokenChange,
-    ]);
+export function OrderTokenAmount({ disabled, inputValue, onChangeInput, context, address, chainId, setChainId, token, setToken, hideTokenSelect = false, canEditAmount = true, className, innerClassName, amountClassName, tokenSelectClassName, onTokenSelect, }) {
     const handleTokenSelect = (newToken) => {
         const token = {
             address: newToken.address,
@@ -80,11 +30,7 @@ export function OrderTokenAmount({ disabled, inputValue, onChangeInput, context,
                 return; // Early return if callback prevented default behavior
             }
         }
-        // Mark that we're about to change tokens
-        prevTokenRef.current = "changing"; // Temporary value to force effect
-        // Set the chain ID first
         setChainId(newToken.chainId);
-        // Then set the new token - the useEffect will handle setting the max balance
         setToken(token);
     };
     return (_jsx("div", { className: cn("border-as-stroke flex w-full flex-col gap-2 rounded-xl", className), children: _jsxs("div", { className: cn("flex items-center justify-between gap-3", innerClassName), children: [!canEditAmount ? (_jsx("h2", { className: cn("text-3xl font-medium text-white", amountClassName), children: inputValue || "--" })) : (_jsx(NumericFormat, { decimalSeparator: ".", allowedDecimalSeparators: [","], thousandSeparator: true, inputMode: "decimal", autoComplete: "off", autoCorrect: "off", type: "text", placeholder: "0.00", minLength: 1, maxLength: 30, spellCheck: "false", className: cn("placeholder:text-as-primary/70 disabled:text-as-primary/70 text-as-primary w-full bg-transparent text-4xl font-semibold leading-[42px] outline-none sm:text-[30px]", amountClassName), pattern: "^[0-9]*[.,]?[0-9]*$", disabled: disabled, value: inputValue, allowNegative: false, onChange: e => onChangeInput(e.currentTarget.value) }, `input-${token.address}-${chainId}`)), !hideTokenSelect && (_jsx(TokenSelector, { address: address, chainIdsFilter: getAvailableChainIds(context), context: context, fromChainWalletVMSupported: true, isValidAddress: true, lockedChainIds: getAvailableChainIds(context), multiWalletSupportEnabled: true, onAnalyticEvent: undefined, popularChainIds: [1, 8453, RELAY_SOLANA_MAINNET_CHAIN_ID], setToken: handleTokenSelect, supportedWalletVMs: ["evm", "svm"], token: undefined, trigger: _jsxs(Button, { variant: "outline", role: "combobox", className: cn("token-selector-button bg-b3-react-background border-as-stroke flex h-auto w-fit shrink-0 items-center justify-center gap-2 rounded-xl border-2 px-2 py-1 pr-2 text-center", tokenSelectClassName), children: [token.metadata.logoURI ? (_jsx(ChainTokenIcon, { chainUrl: ALL_CHAINS[chainId].logoUrl, tokenUrl: token.metadata.logoURI, className: "h-8 min-h-8 w-8 min-w-8" })) : (_jsx("div", { className: "h-8 w-8 rounded-full bg-gray-700" })), _jsxs("div", { className: "flex flex-col items-start gap-0", children: [_jsx("div", { className: "text-as-primary font-semibold", children: token.symbol }), _jsx("div", { className: "text-as-primary/70 text-xs", children: ALL_CHAINS[chainId].name })] }), _jsx(ChevronsUpDown, { className: "h-4 w-4 shrink-0 opacity-70" })] }) }, `selector-${context}-${token.address}-${chainId}`))] }) }, `${context}-${token.address}-${chainId}`));

package/dist/esm/anyspend/react/components/common/PaySection.js

@@ -39,7 +39,7 @@ export function CryptoPaySection({ selectedSrcChainId, setSelectedSrcChainId, se
     useEffect(() => {
         appliedSrcMetadataRef.current = false;
     }, [selectedSrcToken.address, selectedSrcToken.chainId]);
-    return (_jsxs(motion.div, { initial: { opacity: 0, y: 20, filter: "blur(10px)" }, animate: { opacity: 1, y: 0, filter: "blur(0px)" }, transition: { duration: 0.3, delay: 0, ease: "easeInOut" }, className: "pay-section bg-as-surface-secondary border-as-border-secondary relative flex w-full flex-col gap-2 rounded-2xl border p-4 sm:p-6", children: [_jsxs("div", { className: "flex items-center justify-between", children: [_jsx("div", { className: "text-as-primary/50 flex h-7 items-center text-sm", children: "Pay" }), _jsx("button", { className: "text-as-tertiarry flex h-7 items-center gap-2 text-sm transition-colors focus:!outline-none", onClick: onSelectCryptoPaymentMethod, children: selectedCryptoPaymentMethod === CryptoPaymentMethodType.CONNECT_WALLET ? (_jsxs(_Fragment, { children: [isConnected ? (_jsx("div", { className: "flex items-center gap-1", children: connectedName ? formatUsername(connectedName) : shortenAddress(connectedAddress || "") })) : ("Connect wallet"), _jsx(ChevronRight, { className: "h-4 w-4" })] })) : selectedCryptoPaymentMethod === CryptoPaymentMethodType.GLOBAL_WALLET ? (_jsxs(_Fragment, { children: ["Global Account", _jsx(ChevronRight, { className: "h-4 w-4" })] })) : selectedCryptoPaymentMethod === CryptoPaymentMethodType.TRANSFER_CRYPTO ? (_jsxs(_Fragment, { children: ["Transfer crypto", _jsx(ChevronRight, { className: "h-4 w-4" })] })) : (_jsxs(_Fragment, { children: ["Select payment method", _jsx(ChevronRight, { className: "h-4 w-4" })] })) })] }), _jsx(OrderTokenAmount, { address: connectedAddress, walletAddress: connectedAddress, context: "from", inputValue: srcAmount, onChangeInput: value => {
+    return (_jsxs(motion.div, { initial: { opacity: 0, y: 20, filter: "blur(10px)" }, animate: { opacity: 1, y: 0, filter: "blur(0px)" }, transition: { duration: 0.3, delay: 0, ease: "easeInOut" }, className: "pay-section bg-as-surface-secondary border-as-border-secondary relative flex w-full flex-col gap-2 rounded-2xl border p-4 sm:p-6", children: [_jsxs("div", { className: "flex items-center justify-between", children: [_jsx("div", { className: "text-as-primary/50 flex h-7 items-center text-sm", children: "Pay" }), _jsx("button", { className: "text-as-tertiarry flex h-7 items-center gap-2 text-sm transition-colors focus:!outline-none", onClick: onSelectCryptoPaymentMethod, children: selectedCryptoPaymentMethod === CryptoPaymentMethodType.CONNECT_WALLET ? (_jsxs(_Fragment, { children: [isConnected ? (_jsx("div", { className: "flex items-center gap-1", children: connectedName ? formatUsername(connectedName) : shortenAddress(connectedAddress || "") })) : ("Connect wallet"), _jsx(ChevronRight, { className: "h-4 w-4" })] })) : selectedCryptoPaymentMethod === CryptoPaymentMethodType.GLOBAL_WALLET ? (_jsxs(_Fragment, { children: ["Global Account", _jsx(ChevronRight, { className: "h-4 w-4" })] })) : selectedCryptoPaymentMethod === CryptoPaymentMethodType.TRANSFER_CRYPTO ? (_jsxs(_Fragment, { children: ["Transfer crypto", _jsx(ChevronRight, { className: "h-4 w-4" })] })) : (_jsxs(_Fragment, { children: ["Select payment method", _jsx(ChevronRight, { className: "h-4 w-4" })] })) })] }), _jsx(OrderTokenAmount, { address: connectedAddress, context: "from", inputValue: srcAmount, onChangeInput: value => {
                     setIsSrcInputDirty(true);
                     setSrcAmount(value);
                 }, chainId: selectedSrcChainId, setChainId: setSelectedSrcChainId, token: selectedSrcToken, setToken: setSelectedSrcToken }), _jsxs("div", { className: "flex items-center justify-between", children: [_jsx("div", { className: "text-as-primary/50 flex h-5 items-center text-sm", children: formatDisplayNumber(anyspendQuote?.data?.currencyIn?.amountUsd, {

package/dist/esm/anyspend/react/hooks/useAnyspendCreateOnrampOrder.js

@@ -71,6 +71,7 @@ export function useAnyspendCreateOnrampOrder({ onSuccess, onError } = {}) {
                     partnerId,
                     clientReferenceId,
                     visitorData,
+                    callbackMetadata: params.callbackMetadata,
                 });
             }
             catch (error) {

package/dist/esm/anyspend/react/hooks/useAnyspendCreateOrder.d.ts

@@ -18,6 +18,7 @@ export type CreateOrderParams = {
     creatorAddress?: string;
     payload?: any;
     metadata?: Record<string, any>;
+    callbackMetadata?: Record<string, unknown>;
 };
 export type UseAnyspendCreateOrderProps = {
     onSuccess?: (data: any) => void;

package/dist/esm/anyspend/react/hooks/useAnyspendCreateOrder.js

@@ -60,6 +60,7 @@ export function useAnyspendCreateOrder({ onSuccess, onError } = {}) {
                     partnerId,
                     clientReferenceId,
                     visitorData,
+                    callbackMetadata: params.callbackMetadata,
                 });
             }
             catch (error) {

package/dist/esm/anyspend/services/anyspend.d.ts

@@ -6,7 +6,7 @@ export declare const anyspendService: {
     getTokenList: (chainId: number, query: string) => Promise<components["schemas"]["Token"][]>;
     getToken: (chainId: number, tokenAddress: string) => Promise<components["schemas"]["Token"]>;
     getQuote: (req: GetQuoteRequest, partnerId?: string) => Promise<GetQuoteResponse>;
-    createOrder: ({ recipientAddress, type, srcChain, dstChain, srcTokenAddress, dstTokenAddress, srcAmount, payload, onramp, metadata, creatorAddress, partnerId, clientReferenceId, visitorData, }: {
+    createOrder: ({ recipientAddress, type, srcChain, dstChain, srcTokenAddress, dstTokenAddress, srcAmount, payload, onramp, metadata, creatorAddress, partnerId, clientReferenceId, visitorData, callbackMetadata, }: {
         recipientAddress: string;
         type: string;
         srcChain: number;
@@ -21,6 +21,7 @@ export declare const anyspendService: {
         partnerId?: string;
         clientReferenceId?: string;
         visitorData?: VisitorData;
+        callbackMetadata?: Record<string, unknown>;
     }) => Promise<{
         success: boolean;
         message: string;

package/dist/esm/anyspend/services/anyspend.js

@@ -36,7 +36,7 @@ export const anyspendService = {
         return data;
     },
     // Order related
-    createOrder: async ({ recipientAddress, type, srcChain, dstChain, srcTokenAddress, dstTokenAddress, srcAmount, payload, onramp, metadata, creatorAddress, partnerId, clientReferenceId, visitorData, }) => {
+    createOrder: async ({ recipientAddress, type, srcChain, dstChain, srcTokenAddress, dstTokenAddress, srcAmount, payload, onramp, metadata, creatorAddress, partnerId, clientReferenceId, visitorData, callbackMetadata, }) => {
         const accessToken = await app.authentication.getAccessToken();
         const response = await fetch(`${ANYSPEND_MAINNET_BASE_URL}/orders`, {
             method: "POST",
@@ -60,6 +60,7 @@ export const anyspendService = {
                 creatorAddress,
                 partnerId,
                 ...(clientReferenceId && { clientReferenceId }),
+                ...(callbackMetadata && { callbackMetadata }),
             }),
         });
         const data = await response.json();

package/dist/esm/global-account/react/stores/useModalStore.d.ts

@@ -536,6 +536,8 @@ export interface AnySpendDepositModalProps extends BaseModalProps {
     classes?: AnySpendAllClasses;
     /** Whether to allow direct transfer without swap */
     allowDirectTransfer?: boolean;
+    /** Opaque metadata passed to the order for callbacks (e.g., workflow form data) */
+    callbackMetadata?: Record<string, unknown>;
 }
 /**
  * Union type of all possible modal content types

package/dist/types/anyspend/react/components/AnySpend.d.ts

@@ -53,4 +53,6 @@ export declare 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>;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/types/anyspend/react/components/AnySpendCustomExactIn.d.ts

@@ -44,6 +44,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 declare function AnySpendCustomExactIn(props: AnySpendCustomExactInProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/anyspend/react/components/AnySpendDeposit.d.ts

@@ -101,6 +101,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>;
 }
 /**
  * A flexible deposit component that wraps AnySpendCustomExactIn with optional chain selection.
@@ -137,4 +139,4 @@ export interface AnySpendDepositProps {
  *   onSuccess={(amount) => console.log(`Deposited ${amount}`)}
  * />
  */
-export declare function AnySpendDeposit({ loadOrder, mode, recipientAddress, paymentType: initialPaymentType, sourceTokenAddress, sourceTokenChainId: initialSourceChainId, destinationTokenAddress, destinationTokenChainId, onSuccess, onOpenCustomModal, mainFooter, onTokenSelect, customUsdInputValues, preferEoa, minDestinationAmount, header, orderType, depositContractConfig, showChainSelection, supportedChains, minPoolSize, topChainsCount, onClose, returnToHomeUrl, customRecipientLabel, returnHomeLabel, isCustomDeposit, classes, allowDirectTransfer, destinationTokenAmount, }: AnySpendDepositProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function AnySpendDeposit({ loadOrder, mode, recipientAddress, paymentType: initialPaymentType, sourceTokenAddress, sourceTokenChainId: initialSourceChainId, destinationTokenAddress, destinationTokenChainId, onSuccess, onOpenCustomModal, mainFooter, onTokenSelect, customUsdInputValues, preferEoa, minDestinationAmount, header, orderType, depositContractConfig, showChainSelection, supportedChains, minPoolSize, topChainsCount, onClose, returnToHomeUrl, customRecipientLabel, returnHomeLabel, isCustomDeposit, classes, allowDirectTransfer, destinationTokenAmount, callbackMetadata, }: AnySpendDepositProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/anyspend/react/components/common/CryptoPaySection.d.ts

@@ -18,8 +18,6 @@ interface CryptoPaySectionProps {
     }) => void;
     onShowFeeDetail?: () => void;
     classes?: CryptoPaySectionClasses;
-    /** When true, skip auto-setting max balance when token changes (used for fixed destination amount mode) */
-    skipAutoMaxOnTokenChange?: boolean;
 }
-export declare function CryptoPaySection({ selectedSrcChainId, setSelectedSrcChainId, selectedSrcToken, setSelectedSrcToken, srcAmount, setSrcAmount, isSrcInputDirty, setIsSrcInputDirty, selectedCryptoPaymentMethod, onSelectCryptoPaymentMethod, anyspendQuote, onTokenSelect, onShowFeeDetail, classes, skipAutoMaxOnTokenChange, }: CryptoPaySectionProps): import("react/jsx-runtime").JSX.Element;
+export declare function CryptoPaySection({ selectedSrcChainId, setSelectedSrcChainId, selectedSrcToken, setSelectedSrcToken, srcAmount, setSrcAmount, isSrcInputDirty, setIsSrcInputDirty, selectedCryptoPaymentMethod, onSelectCryptoPaymentMethod, anyspendQuote, onTokenSelect, onShowFeeDetail, classes, }: CryptoPaySectionProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/anyspend/react/components/common/OrderTokenAmount.d.ts

@@ -1,5 +1,5 @@
 import { components } from "@b3dotfun/sdk/anyspend/types/api";
-export declare function OrderTokenAmount({ disabled, inputValue, onChangeInput, context, address, chainId, setChainId, token, setToken, hideTokenSelect, canEditAmount, className, innerClassName, amountClassName, tokenSelectClassName, onTokenSelect, walletAddress, skipAutoMaxOnTokenChange, }: {
+export declare function OrderTokenAmount({ disabled, inputValue, onChangeInput, context, address, chainId, setChainId, token, setToken, hideTokenSelect, canEditAmount, className, innerClassName, amountClassName, tokenSelectClassName, onTokenSelect, }: {
     disabled?: boolean;
     inputValue: string;
     onChangeInput: (value: string) => void;
@@ -18,7 +18,4 @@ export declare function OrderTokenAmount({ disabled, inputValue, onChangeInput,
     onTokenSelect?: (token: components["schemas"]["Token"], event: {
         preventDefault: () => void;
     }) => void;
-    walletAddress?: string | undefined;
-    /** When true, skip auto-setting max balance when token changes (used for fixed destination amount mode) */
-    skipAutoMaxOnTokenChange?: boolean;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/types/anyspend/react/hooks/useAnyspendCreateOrder.d.ts

@@ -18,6 +18,7 @@ export type CreateOrderParams = {
     creatorAddress?: string;
     payload?: any;
     metadata?: Record<string, any>;
+    callbackMetadata?: Record<string, unknown>;
 };
 export type UseAnyspendCreateOrderProps = {
     onSuccess?: (data: any) => void;

package/dist/types/anyspend/services/anyspend.d.ts

@@ -6,7 +6,7 @@ export declare const anyspendService: {
     getTokenList: (chainId: number, query: string) => Promise<components["schemas"]["Token"][]>;
     getToken: (chainId: number, tokenAddress: string) => Promise<components["schemas"]["Token"]>;
     getQuote: (req: GetQuoteRequest, partnerId?: string) => Promise<GetQuoteResponse>;
-    createOrder: ({ recipientAddress, type, srcChain, dstChain, srcTokenAddress, dstTokenAddress, srcAmount, payload, onramp, metadata, creatorAddress, partnerId, clientReferenceId, visitorData, }: {
+    createOrder: ({ recipientAddress, type, srcChain, dstChain, srcTokenAddress, dstTokenAddress, srcAmount, payload, onramp, metadata, creatorAddress, partnerId, clientReferenceId, visitorData, callbackMetadata, }: {
         recipientAddress: string;
         type: string;
         srcChain: number;
@@ -21,6 +21,7 @@ export declare const anyspendService: {
         partnerId?: string;
         clientReferenceId?: string;
         visitorData?: VisitorData;
+        callbackMetadata?: Record<string, unknown>;
     }) => Promise<{
         success: boolean;
         message: string;

package/dist/types/global-account/react/stores/useModalStore.d.ts

@@ -536,6 +536,8 @@ export interface AnySpendDepositModalProps extends BaseModalProps {
     classes?: AnySpendAllClasses;
     /** Whether to allow direct transfer without swap */
     allowDirectTransfer?: boolean;
+    /** Opaque metadata passed to the order for callbacks (e.g., workflow form data) */
+    callbackMetadata?: Record<string, unknown>;
 }
 /**
  * Union type of all possible modal content types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b3dotfun/sdk",
-  "version": "0.1.65-alpha.5",
+  "version": "0.1.65-alpha.7",
   "source": "src/index.ts",
   "main": "./dist/cjs/index.js",
   "react-native": "./dist/cjs/index.native.js",

package/src/anyspend/README.md

@@ -81,6 +81,7 @@ That's it! Your users can now purchase NFTs with any token from any supported ch
 | [🧩 Components API](./docs/components.md) | Pre-built React components for common use cases |
 | [🪝 Hooks API](./docs/hooks.md) | React hooks for custom implementations |
 | [💡 Examples & Use Cases](./docs/examples.md) | Real-world integration examples |
+| [🛒 Checkout Sessions](./docs/checkout-sessions.md) | Stripe-like checkout sessions for merchant integrations |
 | [⚠️ Error Handling](./docs/error-handling.md) | Error handling patterns and troubleshooting |
 | [🤝 Contributing](./docs/contributing.md) | How to contribute to AnySpend |
 
@@ -123,6 +124,19 @@ That's it! Your users can now purchase NFTs with any token from any supported ch
 />
 ```
 
+### Merchant Checkout Sessions
+```tsx
+<AnySpend
+  defaultActiveTab="fiat"
+  destinationTokenAddress="0x..." // USDC
+  recipientAddress={userAddress}
+  checkoutSession={{
+    success_url: "https://myshop.com/success?session={SESSION_ID}",
+    metadata: { sku: "widget-1" },
+  }}
+/>
+```
+
 ## 🌐 Supported Networks
 
 - **Ethereum** (Mainnet & Sepolia)

package/src/anyspend/docs/checkout-sessions.md

@@ -0,0 +1,228 @@
+# Checkout Sessions
+
+Stripe-like checkout sessions for AnySpend. Sessions are decoupled from orders — create a session first, then create an order when the user is ready to pay.
+
+## Flow
+
+```
+1. Merchant creates session        POST /checkout-sessions
+                                   <- { id, status: "open" }
+
+2. User picks payment method       POST /orders { checkoutSessionId }
+                                   <- { id, globalAddress, oneClickBuyUrl }
+
+3. User pays                       Crypto: send to globalAddress
+                                   Onramp: redirect to oneClickBuyUrl
+
+4. Merchant polls for completion   GET /checkout-sessions/:id
+                                   <- { status: "complete", order_id }
+```
+
+### Why Decoupled?
+
+Session creation is instant (DB-only, no external calls). The order is created separately when the user commits to a payment method. This means:
+
+- Payment method doesn't need to be known at session creation
+- A hosted checkout page can let users choose how to pay
+- Session creation never fails due to external API errors
+
+## Session Status Lifecycle
+
+```
+open --> processing --> complete
+  |
+  └--> expired
+```
+
+| Status | When |
+|--------|------|
+| `open` | Created, waiting for order/payment |
+| `processing` | Payment received, order executing |
+| `complete` | Order executed successfully |
+| `expired` | TTL expired, payment failed, or manually expired |
+
+## API
+
+### `POST /checkout-sessions` — Create Session
+
+Creates a lightweight session. No order, no external API calls.
+
+```json
+{
+  "success_url": "https://merchant.com/success?session_id={SESSION_ID}",
+  "cancel_url": "https://merchant.com/cancel",
+  "metadata": { "sku": "widget-1" },
+  "client_reference_id": "merchant-order-456",
+  "expires_in": 1800
+}
+```
+
+All fields are optional. Payment config (amount, tokens, chains) lives on the order, not the session.
+
+### `POST /orders` — Create Order with Session Linking
+
+Pass `checkoutSessionId` in the standard order creation request to link the order to a session.
+
+```json
+{
+  "recipientAddress": "0x...",
+  "srcChain": 8453,
+  "dstChain": 8453,
+  "srcTokenAddress": "0x...",
+  "dstTokenAddress": "0x...",
+  "srcAmount": "1000000",
+  "type": "swap",
+  "payload": { "expectedDstAmount": "1000000" },
+  "checkoutSessionId": "550e8400-..."
+}
+```
+
+**Validation:**
+- Session must exist (`400` if not found)
+- Session must be `open` (`400` if expired/processing/complete)
+- Session must not already have an order (`409 Conflict`)
+
+### `GET /checkout-sessions/:id` — Retrieve Session
+
+Returns current session state. Status is synced from the underlying order on each retrieval.
+
+| Query Param | Description |
+|-------------|-------------|
+| `include=order` | Embed the full order object with transactions |
+
+### `POST /checkout-sessions/:id/expire` — Manually Expire
+
+Only works on sessions with status `open`.
+
+## Redirect URL Templates
+
+Use template variables in `success_url` and `cancel_url`:
+
+| Variable | Replaced with |
+|----------|--------------|
+| `{SESSION_ID}` | The checkout session UUID |
+| `{ORDER_ID}` | Same value (alias) |
+
+If no template variable is present, `?sessionId=<uuid>` is appended automatically.
+
+## SDK Integration
+
+### Service Methods
+
+```typescript
+// Create a checkout session
+const session = await anyspend.createCheckoutSession({
+  success_url: "https://mysite.com/success/{SESSION_ID}",
+  metadata: { sku: "widget-1" },
+});
+
+// Retrieve session status
+const session = await anyspend.getCheckoutSession(sessionId);
+```
+
+### React Hooks
+
+#### `useCreateCheckoutSession`
+
+Mutation hook for creating sessions.
+
+```tsx
+import { useCreateCheckoutSession } from "@b3dotfun/sdk/anyspend";
+
+const { mutate: createSession, data, isPending } = useCreateCheckoutSession();
+```
+
+#### `useCheckoutSession`
+
+Query hook with auto-polling. Stops polling when status reaches `complete` or `expired`.
+
+```tsx
+import { useCheckoutSession } from "@b3dotfun/sdk/anyspend";
+
+const { data: session, isLoading } = useCheckoutSession(sessionId);
+```
+
+### Component `checkoutSession` Prop
+
+The `<AnySpend>`, `<AnySpendCustom>`, and `<AnySpendCustomExactIn>` components accept an optional `checkoutSession` prop:
+
+```tsx
+<AnySpend
+  defaultActiveTab="fiat"
+  destinationTokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+  destinationTokenChainId={8453}
+  recipientAddress="0x..."
+  checkoutSession={{
+    success_url: "https://myshop.com/success?session={SESSION_ID}",
+    cancel_url: "https://myshop.com/cancel",
+    metadata: { sku: "widget-1" },
+  }}
+/>
+```
+
+When the `checkoutSession` prop is set, the component automatically creates a session before creating the order, and uses the session's `success_url` for redirects. Without the prop, existing flows are unchanged.
+
+## Examples
+
+### Crypto Payment
+
+```typescript
+// 1. Create session
+const session = await fetch("/checkout-sessions", {
+  method: "POST",
+  body: JSON.stringify({
+    success_url: "https://mysite.com/success/{SESSION_ID}",
+    metadata: { sku: "widget-1" },
+  }),
+}).then(r => r.json());
+
+// 2. Create order linked to session
+const order = await fetch("/orders", {
+  method: "POST",
+  body: JSON.stringify({
+    recipientAddress: "0x...",
+    srcChain: 8453,
+    dstChain: 8453,
+    srcTokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    dstTokenAddress: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    srcAmount: "1000000",
+    type: "swap",
+    payload: { expectedDstAmount: "1000000" },
+    checkoutSessionId: session.data.id,
+  }),
+}).then(r => r.json());
+
+// 3. User sends crypto to order.data.globalAddress
+
+// 4. Poll session until complete
+const poll = setInterval(async () => {
+  const s = await fetch(`/checkout-sessions/${session.data.id}`).then(r => r.json());
+  if (s.data.status === "complete") {
+    clearInterval(poll);
+    // redirect to success_url or show confirmation
+  }
+}, 3000);
+```
+
+### Onramp Payment (Coinbase/Stripe)
+
+```typescript
+// Steps 1-2 same as above, but include onramp config in order creation:
+const order = await fetch("/orders", {
+  method: "POST",
+  body: JSON.stringify({
+    // ... same order fields ...
+    checkoutSessionId: session.data.id,
+    onramp: {
+      vendor: "coinbase",
+      payment_method: "card",
+      country: "US",
+    },
+  }),
+}).then(r => r.json());
+
+// Redirect user to vendor checkout page
+window.location.href = order.data.oneClickBuyUrl;
+
+// After vendor redirects back, poll GET /checkout-sessions/:id for completion
+```

package/src/anyspend/docs/components.md

@@ -207,6 +207,32 @@ const stakingCalldata = encodeFunctionData({
 />
 ```
 
+### Checkout Session Prop
+
+The `<AnySpend>`, `<AnySpendCustom>`, and `<AnySpendCustomExactIn>` components accept an optional `checkoutSession` prop for merchant checkout flows. When set, the component creates a session before the order and uses the session's redirect URLs. See [Checkout Sessions](./checkout-sessions.md) for the full guide.
+
+```tsx
+<AnySpend
+  defaultActiveTab="fiat"
+  destinationTokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+  destinationTokenChainId={8453}
+  recipientAddress="0x..."
+  checkoutSession={{
+    success_url: "https://myshop.com/success?session={SESSION_ID}",
+    cancel_url: "https://myshop.com/cancel",
+    metadata: { sku: "widget-1" },
+  }}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `checkoutSession.success_url` | `string` | Redirect URL on completion. Supports `{SESSION_ID}` template. |
+| `checkoutSession.cancel_url` | `string` | Redirect URL on cancellation |
+| `checkoutSession.metadata` | `Record<string, string>` | Custom metadata attached to the session |
+
+---
+
 ## Specialized Components
 
 ### `<AnySpendNFT>`

package/src/anyspend/docs/examples.md

@@ -720,8 +720,66 @@ function PortfolioRebalancer() {
 }
 ```
 
+## 🛒 Checkout Sessions (Merchant Integration)
+
+### Hosted Checkout with Payment Choice
+
+Let users choose their payment method (crypto or fiat) after session creation.
+
+```tsx
+import { AnySpend } from "@b3dotfun/sdk/anyspend/react";
+
+function MerchantCheckout({ sku, price }: { sku: string; price: string }) {
+  const [userAddress] = useWallet();
+
+  return (
+    <AnySpend
+      defaultActiveTab="fiat"
+      destinationTokenAddress="0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+      destinationTokenChainId={8453}
+      recipientAddress={userAddress}
+      checkoutSession={{
+        success_url: "https://myshop.com/success?session={SESSION_ID}",
+        cancel_url: "https://myshop.com/cancel",
+        metadata: { sku, price },
+      }}
+    />
+  );
+}
+```
+
+### Server-Side Session with Custom Polling
+
+```tsx
+import {
+  useCreateCheckoutSession,
+  useCheckoutSession,
+} from "@b3dotfun/sdk/anyspend";
+
+function ServerCheckout() {
+  const { mutate: createSession, data: session } = useCreateCheckoutSession();
+  const { data: sessionStatus } = useCheckoutSession(session?.data?.id);
+
+  useEffect(() => {
+    createSession({
+      success_url: "https://mysite.com/success/{SESSION_ID}",
+      metadata: { sku: "widget-1" },
+    });
+  }, []);
+
+  if (sessionStatus?.data?.status === "complete") {
+    return <div>Payment complete!</div>;
+  }
+
+  // Render order creation UI...
+}
+```
+
+See [Checkout Sessions](./checkout-sessions.md) for the full guide including API details and the session lifecycle.
+
 ## Next Steps
 
+- [Checkout Sessions →](./checkout-sessions.md)
 - [Error Handling Guide →](./error-handling.md)
 - [Components Reference →](./components.md)
 - [Hooks Reference →](./hooks.md)