@b3dotfun/sdk 0.0.9-alpha.1 → 0.0.9-alpha.3

package/src/anyspend/README.md

@@ -1,52 +1,24 @@
-# AnySpend SDK Documentation
+# AnySpend SDK
 
-The fastest way to accept crypto payments and onboard users with zero friction
+**The fastest way to accept crypto payments and onboard users with zero friction.**
 
-AnySpend gives you everything you need to add instant crypto onramps and checkout to your product. Let your users onramp from fiat instantly and pay using any token on any chain, all in one seamless experience.
+AnySpend gives you everything you need to add instant crypto onramps and checkout to your product. Let your users pay with any token on any chain, all in one seamless experience.
 
-- 🚀 **Instant Onramp:** Users can fund their wallet directly from fiat and start spending in your app right away
-- 💸 **Pay Anyway:** Accept payments in any token across any chain with no bridges, swapping, or network switching required
-- 🧩 **One SDK, Any Flow:** Easily add crypto payments and onramps to any business model or checkout flow
-- 👛 **Unified Wallet View:** Users see and spend their balances from all chains in one place
+## ✨ Why AnySpend?
 
-AnySpend makes it simple to reach more users, increase conversions, and future proof your business with modern crypto payments.
+- 🚀 **Instant Onramp** — Users fund wallets directly from fiat and start spending immediately
+- 💸 **Pay with Anything** — Accept payments in any token across any chain, no bridges required
+- 🧩 **One SDK, Any Flow** — Easily integrate crypto payments into any business model
+- 👛 **Unified Experience** — Users see and spend balances from all chains in one place
 
-See the Quickstart below or visit anyspend.com for a live demo
+Perfect for NFT marketplaces, gaming, DeFi, e-commerce, and any application that needs seamless crypto payments.
 
-AnySpend is a powerful cross-chain protocol that enables seamless token swaps, NFT minting, tournament participation, and custom smart contract interactions across multiple blockchain networks. Built for developers who want to provide their users with a frictionless Web3 experience.
-
-## 📦 Overview
-
-AnySpend handles the complexity of cross-chain operations, gas management, and payment processing, allowing users to:
-
-- **Cross-chain Swaps**: Swap tokens across different blockchain networks
-- **NFT Minting**: Mint NFTs with automatic payment handling
-- **Custom Interactions**: Execute any smart contract operations (tournaments, staking, gaming, etc.)
-- **Fiat Onramp**: Convert fiat currency to crypto using integrated payment providers
-- **Gasless Transactions**: Users don't need to worry about gas fees
-
-### Key Features
-
-- **Multi-chain Support**: Works across Ethereum, Base, B3, and other supported networks
-- **Payment Flexibility**: Accept payments in various cryptocurrencies or fiat
-- **Order Management**: Track transaction status in real-time
-- **Error Recovery**: Automatic refund handling for failed transactions
-- **React Integration**: Pre-built components for easy integration
-- **TypeScript Support**: Full type safety and IntelliSense
-
-## 🚀 Getting Started
-
-### Prerequisites
-
-- Node.js v20.15.0+
-- React 18/19
+## 🚀 Quick Start
 
 ### Installation
 
 ```bash
 npm install @b3dotfun/sdk
-# or
-pnpm add @b3dotfun/sdk
 ```
 
 ### Basic Setup
@@ -56,24 +28,28 @@ import { AnySpendProvider } from "@b3dotfun/sdk/anyspend/react";
 import "@b3dotfun/sdk/index.css";
 
 function App() {
-  return <AnySpendProvider>{/* Your app components */}</AnySpendProvider>;
+  return (
+    <AnySpendProvider>
+      {/* Your app components */}
+    </AnySpendProvider>
+  );
 }
 ```
 
-### Quick Start Example
+### Your First Payment
 
 ```tsx
 import { AnySpendNFTButton } from "@b3dotfun/sdk/anyspend/react";
 
-function NFTMinting() {
+function NFTCard() {
   const nftContract = {
-    chainId: 8333, // B3 network
+    chainId: 8333,
     contractAddress: "0x9c275ff1634519E9B5449ec79cd939B5F900564d",
     price: "500000000000000000", // 0.5 ETH in wei
     priceFormatted: "0.5",
     currency: {
       chainId: 8333,
-      address: "0x0000000000000000000000000000000000000000", // ETH
+      address: "0x0000000000000000000000000000000000000000",
       name: "Ether",
       symbol: "ETH",
       decimals: 18,
@@ -87,553 +63,91 @@ function NFTMinting() {
     <AnySpendNFTButton
       nftContract={nftContract}
       recipientAddress="0x..." // User's wallet address
-      onSuccess={txHash => {
-        console.log("NFT minted successfully!", txHash);
+      onSuccess={(txHash) => {
+        console.log("NFT purchased!", txHash);
       }}
     />
   );
 }
 ```
 
-## 📚 API Reference
+That's it! Your users can now purchase NFTs with any token from any supported chain.
 
-### Components
+## 📖 Documentation
 
-#### `<AnySpend>`
+| Guide | Description |
+|-------|-------------|
+| [📦 Installation & Setup](./docs/installation.md) | Get started with AnySpend in your project |
+| [🧩 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 |
+| [⚠️ Error Handling](./docs/error-handling.md) | Error handling patterns and troubleshooting |
+| [🤝 Contributing](./docs/contributing.md) | How to contribute to AnySpend |
 
-The main swap interface component for token-to-token exchanges.
+## 🎯 What You Can Build
 
+### Cross-Chain DeFi
 ```tsx
-<AnySpend
-  isMainnet={true}
-  mode="modal" // or "page"
-  defaultActiveTab="crypto" // or "fiat"
-  destinationTokenAddress="0x..." // For buy mode
-  destinationTokenChainId={8333}
-  recipientAddress="0x..."
-  hideTransactionHistoryButton={false}
-  onSuccess={txHash => console.log("Swap completed", txHash)}
+<AnySpend 
+  mode="page"
+  recipientAddress={userAddress}
+  onSuccess={(txHash) => updatePortfolio(txHash)}
 />
 ```
 
-**Props:**
-
-- `isMainnet?: boolean` - Whether to use mainnet or testnet (default: `true`)
-- `mode?: "modal" | "page"` - Display mode (default: `"modal"`)
-- `defaultActiveTab?: "crypto" | "fiat"` - Initial payment method (default: `"crypto"`)
-- `destinationTokenAddress?: string` - For buy mode, specify the target token
-- `destinationTokenChainId?: number` - Chain ID of the destination token
-- `recipientAddress?: string` - Where to send the swapped tokens
-- `hideTransactionHistoryButton?: boolean` - Hide the transaction history button
-- `loadOrder?: string` - Load a specific order by ID
-- `onSuccess?: (txHash?: string) => void` - Success callback
-
-#### `<AnySpendNFTButton>`
-
-A simple button component for NFT minting.
-
+### NFT Marketplaces
 ```tsx
 <AnySpendNFTButton
-  nftContract={{
-    chainId: 8333,
-    contractAddress: "0x...",
-    price: "1000000000000000000", // 1 ETH in wei
-    priceFormatted: "1.0",
-    currency: {
-      /* token details */
-    },
-    name: "My NFT",
-    description: "NFT description",
-    imageUrl: "https://example.com/image.png",
-  }}
-  recipientAddress="0x..."
-  isMainnet={true}
+  nftContract={nftDetails}
+  recipientAddress={userAddress}
+  onSuccess={(txHash) => showSuccess(txHash)}
 />
 ```
 
-#### `<AnySpendCustom>`
-
-For custom smart contract interactions.
-
+### Gaming & Staking
 ```tsx
 <AnySpendCustom
-  orderType={"custom"}
-  dstChainId={8333}
-  dstToken={
-    {
-      /* token details */
-    }
-  }
-  dstAmount="1000000000000000000" // Amount in wei
-  contractAddress="0x..." // Target contract
-  encodedData="0x..." // Encoded function call
-  spenderAddress="0x..." // Optional spender
-  metadata={
-    {
-      /* custom metadata */
-    }
-  }
-  header={({ anyspendPrice, isLoadingAnyspendPrice }) => <div>Custom header content</div>}
-  onSuccess={txHash => console.log("Custom order completed", txHash)}
+  orderType="custom"
+  contractAddress="0x..."
+  encodedData="0x..." // stake() function call
+  onSuccess={(txHash) => updateStakePosition(txHash)}
 />
 ```
 
-> **Note**: For specific use cases like staking, spin wheels, or other gaming mechanics, there are specialized components available (`AnySpendStakeB3`, `AnySpendBuySpin`, etc.). However, `AnySpendCustom` provides the most flexibility for any smart contract interaction.
-
-### Hooks
-
-#### `useAnyspendQuote`
-
-Get pricing information for a potential order.
-
-```tsx
-import { useAnyspendQuote } from "@b3dotfun/sdk/anyspend";
-
-const { anyspendQuote, isLoadingAnyspendQuote, getAnyspendQuoteError } = useAnyspendQuote(
-  true, // isMainnet
-  {
-    srcChain: 1, // Ethereum
-    dstChain: 8333, // B3
-    srcTokenAddress: "0x...", // USDC
-    dstTokenAddress: "0x...", // Target token
-    type: "swap",
-    tradeType: "EXACT_INPUT",
-    amount: "1000000", // 1 USDC (6 decimals)
-  },
-);
-```
-
-#### `useAnyspendCreateOrder`
-
-Create a new AnySpend order.
-
+### Fiat Onboarding
 ```tsx
-import { useAnyspendCreateOrder } from "@b3dotfun/sdk/anyspend";
-
-const { createOrder, isCreatingOrder } = useAnyspendCreateOrder({
-  onSuccess: data => {
-    console.log("Order created:", data.data.id);
-  },
-  onError: error => {
-    console.error("Order creation failed:", error.message);
-  },
-});
-
-// Create order
-createOrder({
-  isMainnet: true,
-  recipientAddress: "0x...",
-  orderType: "swap",
-  srcChain: 1,
-  dstChain: 8333,
-  srcToken: {
-    /* source token details */
-  },
-  dstToken: {
-    /* destination token details */
-  },
-  srcAmount: "1000000",
-  expectedDstAmount: "500000000000000000",
-  creatorAddress: "0x...",
-});
-```
-
-#### `useAnyspendOrderAndTransactions`
-
-Track order status and associated transactions.
-
-```tsx
-import { useAnyspendOrderAndTransactions } from "@b3dotfun/sdk/anyspend";
-
-const { orderAndTransactions, getOrderAndTransactionsError } = useAnyspendOrderAndTransactions(
-  true, // isMainnet
-  "order-id-here",
-);
-
-if (orderAndTransactions) {
-  const { order, depositTxs, relayTx, executeTx, refundTxs } = orderAndTransactions.data;
-  console.log("Order status:", order.status);
-  console.log("Deposit transactions:", depositTxs);
-  console.log("Execution transaction:", executeTx);
-}
-```
-
-#### `useAnyspendOrderHistory`
-
-Get order history for a user.
-
-```tsx
-import { useAnyspendOrderHistory } from "@b3dotfun/sdk/anyspend";
-
-const { orderHistory, isLoadingOrderHistory } = useAnyspendOrderHistory(
-  true, // isMainnet
-  "0x...", // creatorAddress
-  50, // limit
-  0, // offset
-);
-```
-
-### Service Functions
-
-For advanced use cases, you can use the service layer directly:
-
-```tsx
-import { anyspendService } from "@b3dotfun/sdk/anyspend/services";
-
-// Get quote
-const quote = await anyspendService.getQuote(true, {
-  srcChain: 1,
-  dstChain: 8333,
-  srcTokenAddress: "0x...",
-  dstTokenAddress: "0x...",
-  type: "swap",
-  tradeType: "exactInput",
-  amount: "1000000",
-});
-
-// Get token list
-const tokens = await anyspendService.getTokenList(true, 1, "USDC");
-
-// Create order
-const order = await anyspendService.createOrder({
-  isMainnet: true,
-  recipientAddress: "0x...",
-  type: "swap",
-  srcChain: 1,
-  dstChain: 8333,
-  srcTokenAddress: "0x...",
-  dstTokenAddress: "0x...",
-  srcAmount: "1000000",
-  payload: {
-    /* order payload */
-  },
-  metadata: {
-    /* order metadata */
-  },
-});
-```
-
-### Network Configuration
-
-AnySpend automatically configures API endpoints based on the `isMainnet` parameter:
-
-- **Mainnet**: `https://mainnet.anyspend.com`
-- **Testnet**: `http://testnet.anyspend.com`
-
-## 💼 Common Use Cases
-
-### 1. Cross-Chain Token Swap
-
-```tsx
-import { AnySpend } from "@b3dotfun/sdk/anyspend/react";
-
-function TokenSwap() {
-  return (
-    <AnySpend
-      mode="page"
-      recipientAddress="0x..."
-      onSuccess={txHash => {
-        console.log("Swap completed:", txHash);
-        // Redirect user or show success message
-      }}
-    />
-  );
-}
-```
-
-### 2. NFT Marketplace Integration
-
-```tsx
-import { AnySpendNFT } from "@b3dotfun/sdk/anyspend/react";
-
-function NFTCard({ nft }) {
-  return (
-    <div className="nft-card">
-      <img src={nft.imageUrl} alt={nft.name} />
-      <h3>{nft.name}</h3>
-      <p>{nft.description}</p>
-      <AnySpendNFT
-        nftContract={nft}
-        recipientAddress={userAddress}
-        onSuccess={txHash => {
-          // Update UI to show NFT as owned
-          updateNFTOwnership(nft.id, userAddress);
-        }}
-      />
-    </div>
-  );
-}
-```
-
-### 3. Custom Contract Interaction - Staking Example
-
-```tsx
-import { AnySpendCustom } from "@b3dotfun/sdk/anyspend/react";
-
-function StakingInterface({ stakingContract }) {
-  return (
-    <AnySpendCustom
-      orderType={"custom"}
-      dstChainId={stakingContract.chainId}
-      dstToken={stakingContract.stakingToken}
-      dstAmount={stakingContract.stakeAmount}
-      contractAddress={stakingContract.contractAddress}
-      encodedData={stakingContract.stakeCalldata} // encoded stake() function call
-      metadata={{
-        action: "stake",
-        staking: {
-          contractAddress: stakingContract.contractAddress,
-          amount: stakingContract.stakeAmount,
-          duration: stakingContract.duration,
-        },
-      }}
-      header={({ anyspendPrice }) => (
-        <div className="staking-header">
-          <h2>Stake {stakingContract.stakingToken.symbol}</h2>
-          <p>
-            Amount: {stakingContract.stakeAmountFormatted} {stakingContract.stakingToken.symbol}
-          </p>
-          <p>Duration: {stakingContract.duration} days</p>
-        </div>
-      )}
-      onSuccess={txHash => {
-        console.log("Staking completed:", txHash);
-        // Update UI to show staked amount
-      }}
-    />
-  );
-}
-```
-
-### 4. Fiat to Crypto Onramp
-
-```tsx
-import { AnySpend } from "@b3dotfun/sdk/anyspend/react";
-
-function FiatOnramp() {
-  return (
-    <AnySpend
-      defaultActiveTab="fiat"
-      destinationTokenAddress="0x..." // Target token to buy
-      destinationTokenChainId={8333}
-      recipientAddress="0x..."
-      onSuccess={txHash => {
-        console.log("Fiat purchase completed:", txHash);
-      }}
-    />
-  );
-}
-```
-
-## ⚠️ Error Handling
-
-### Order Status Types
-
-AnySpend orders go through various states:
-
-```typescript
-enum OrderStatus {
-  // Preparation
-  ScanningDepositTransaction = "scanning_deposit_transaction",
-  WaitingStripePayment = "waiting_stripe_payment",
-  ObtainToken = "obtain_token",
-
-  // Execution
-  SendingTokenFromVault = "sending_token_from_vault",
-  Relay = "relay",
-  Executed = "executed",
-
-  // Failure/Refund
-  ObtainFailed = "obtain_failed",
-  Expired = "expired",
-  Refunding = "refunding",
-  Refunded = "refunded",
-  Failure = "failure",
-}
-```
-
-### Common Error Codes
-
-| Error Code             | Description                       | Recovery Strategy                    |
-| ---------------------- | --------------------------------- | ------------------------------------ |
-| `SLIPPAGE`             | Price movement exceeded tolerance | Retry with higher slippage tolerance |
-| `INSUFFICIENT_BALANCE` | User doesn't have enough tokens   | Request user to add funds            |
-| `NETWORK_ERROR`        | RPC or network issues             | Retry after a delay                  |
-| `QUOTE_EXPIRED`        | Price quote is no longer valid    | Get a fresh quote                    |
-
-### Error Handling Best Practices
-
-```tsx
-import { useAnyspendCreateOrder } from "@b3dotfun/sdk/anyspend";
-
-const { createOrder, isCreatingOrder } = useAnyspendCreateOrder({
-  onError: error => {
-    switch (error.message) {
-      case "SLIPPAGE":
-        toast.error("Price moved unfavorably. Please try again.");
-        break;
-      case "INSUFFICIENT_BALANCE":
-        toast.error("Insufficient balance. Please add funds to your wallet.");
-        break;
-      default:
-        toast.error("Transaction failed. Please try again or contact support.");
-    }
-
-    // Log for debugging
-    console.error("Order creation failed:", error);
-
-    // Optional: Send to error tracking service
-    // errorTracking.captureException(error);
-  },
-});
-```
-
-### Order Monitoring
-
-```tsx
-import { useAnyspendOrderAndTransactions, OrderStatus } from "@b3dotfun/sdk/anyspend";
-
-function OrderTracker({ orderId }) {
-  const { orderAndTransactions } = useAnyspendOrderAndTransactions(true, orderId);
-
-  if (!orderAndTransactions) return <div>Loading...</div>;
-
-  const { order, depositTxs, executeTx, refundTxs } = orderAndTransactions.data;
-
-  const getStatusMessage = (status: OrderStatus) => {
-    switch (status) {
-      case "scanning_deposit_transactions":
-        return "Waiting for payment confirmation...";
-      case "relay":
-        return "Processing your transaction...";
-      case "executed":
-        return "Transaction completed successfully!";
-      case "failure":
-        return "Transaction failed. You will be refunded automatically.";
-      case "refunded":
-        return "Refund processed successfully.";
-      default:
-        return "Processing...";
-    }
-  };
-
-  return (
-    <div className="order-status">
-      <h3>Order Status: {order.status}</h3>
-      <p>{getStatusMessage(order.status)}</p>
-
-      {order.errorDetails && (
-        <div className="error-details">
-          <strong>Error:</strong> {order.errorDetails}
-        </div>
-      )}
-
-      {executeTx && (
-        <a href={`https://explorer.b3.fun/tx/${executeTx.txHash}`} target="_blank" rel="noopener noreferrer">
-          View Transaction
-        </a>
-      )}
-    </div>
-  );
-}
-```
-
-## 🌐 Platform Support
-
-| Feature           | React Web | React Native |
-| ----------------- | --------- | ------------ |
-| Core AnySpend     | ✅        | ✅           |
-| React Components  | ✅        | ✅           |
-| Fiat Onramp       | ✅        | ❌           |
-| NFT Components    | ✅        | ✅           |
-| Service Functions | ✅        | ✅           |
-
-## 🐛 Troubleshooting
-
-### Common Issues
-
-**Q: "Get rate error" appears when trying to swap**
-
-```
-A: This usually means:
-1. Invalid token addresses
-2. Unsupported token pair
-3. Amount too small/large
-4. Network connectivity issues
-
-Check that both tokens are supported and try with a different amount.
-```
-
-**Q: Order stuck in "scanning_deposit_transaction" status**
-
-```
-A: This means AnySpend is waiting for your deposit transaction to be confirmed.
-Check that:
-1. You sent the correct amount
-2. Transaction was confirmed on-chain
-3. You sent to the correct address
-
-Orders will auto-refund after 30 minutes if no deposit is detected.
-```
-
-**Q: React Native build issues**
-
-```
-A: Make sure you're importing from the correct entry point:
-
-// ✅ Correct
-import { anyspendService } from "@b3dotfun/sdk/anyspend";
-
-// ❌ Incorrect for React Native
-import { AnySpend } from "@b3dotfun/sdk/anyspend/react";
+<AnySpend
+  defaultActiveTab="fiat"
+  destinationTokenAddress="0x..." // USDC
+  recipientAddress={userAddress}
+/>
 ```
 
-### Debug Mode
-
-Enable debug logging to troubleshoot issues:
-
-```typescript
-// Add to your app initialization
-localStorage.setItem("debug", "anyspend:*");
-
-// Or in React Native
-import { anyspendService } from "@b3dotfun/sdk/anyspend";
+## 🌐 Supported Networks
 
-// Service calls will now log detailed information
-const quote = await anyspendService.getQuote(true, quoteRequest);
-```
-
-### Support Channels
+- **Ethereum** (Mainnet & Sepolia)
+- **Base** (Mainnet & Sepolia) 
+- **B3** (Mainnet & Testnet)
+- **More networks coming soon**
 
-- **Documentation**: [https://docs.b3.fun](https://docs.b3.fun)
-- **GitHub Issues**: [https://github.com/b3-fun/b3/issues](https://github.com/b3-fun/b3/issues)
-- **Discord**: [https://discord.gg/b3dotfun](https://discord.gg/b3dotfun)
+## 🛠️ Platform Support
 
-## 🤝 Contributing
+| Platform | Components | Hooks | Services |
+|----------|------------|-------|----------|
+| **React Web** | ✅ | ✅ | ✅ |
+| **React Native** | 🚧 | ✅ | ✅ |
+| **Node.js** | ❌ | ❌ | ✅ |
 
-We welcome contributions! Here's how to get started:
+## 💬 Community & Support
 
-1. **Fork the repository**
-2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
-3. **Install dependencies**: `pnpm install`
-4. **Run tests**: `pnpm test`
-5. **Build the SDK**: `pnpm sdk:build`
-6. **Test your changes** in the example apps
-7. **Submit a pull request**
+- 📚 **[Live Demo](https://anyspend.com)** — Try AnySpend in action
+- 💬 **[Discord](https://discord.gg/b3dotfun)** — Join our developer community  
+- 🐛 **[GitHub Issues](https://github.com/b3-fun/b3/issues)** — Report bugs or request features
+- 📖 **[Full Documentation](https://docs.b3.fun)** — Complete guides and API reference
 
-### Development Setup
+---
 
-```bash
-# Clone the repo
-git clone https://github.com/b3-fun/b3.git
-cd b3
+**Ready to revolutionize payments in your app?** [Get started with the installation guide →](./docs/installation.md)
 
-# Install dependencies
-pnpm install
 
-# Start development
-pnpm dev
 
-# Build the SDK
-pnpm sdk:build
-```