@b3dotfun/sdk 0.1.65 → 0.1.66-alpha.1

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)

package/src/anyspend/docs/hooks.md

@@ -385,6 +385,38 @@ Get Stripe payment intent for credit card payments.
 const { clientSecret, isLoadingClientSecret } = useStripeClientSecret(orderData);
 ```
 
+### `useCreateCheckoutSession`
+
+Create checkout sessions for merchant integrations. See [Checkout Sessions](./checkout-sessions.md) for the full guide.
+
+```tsx
+import { useCreateCheckoutSession } from "@b3dotfun/sdk/anyspend";
+
+const { mutate: createSession, data, isPending } = useCreateCheckoutSession();
+
+createSession({
+  success_url: "https://mysite.com/success/{SESSION_ID}",
+  cancel_url: "https://mysite.com/cancel",
+  metadata: { sku: "widget-1" },
+});
+```
+
+---
+
+### `useCheckoutSession`
+
+Poll a checkout session's status. Auto-polls while the session is `open` or `processing`, and stops when `complete` or `expired`.
+
+```tsx
+import { useCheckoutSession } from "@b3dotfun/sdk/anyspend";
+
+const { data: session, isLoading } = useCheckoutSession(sessionId);
+
+// session.data.status: "open" | "processing" | "complete" | "expired"
+```
+
+---
+
 ## Hook Patterns
 
 ### Error Handling Pattern

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