@b3dotfun/anyspend-sdk

AnySpend SDK

A React SDK for integrating with the Anyspend protocol, providing hooks and utilities for cross-chain token transfers and management.

Installation

npm install @b3dotfun/anyspend-sdk
# or
yarn add @b3dotfun/anyspend-sdk
# or
pnpm add @b3dotfun/anyspend-sdk

Requirements

• React 16.8+
• TanStack Query (React Query) v4+
• Viem

Setup

The SDK uses TanStack Query for data fetching and caching. You need to wrap your application or the components using AnySpend hooks with the AnyspendProvider:

import { AnyspendProvider } from '@b3dotfun/anyspend-sdk';

// App-level setup (in your root layout)
function App() {
  return (
    <AnyspendProvider>
      <YourApp />
    </AnyspendProvider>
  );
}

// OR

// Component-level setup (for specific pages/components)
function YourComponent() {
  return (
    <AnyspendProvider>
      <YourAnyspendFeature />
    </AnyspendProvider>
  );
}

Important notes about the provider:

• Must be mounted before any AnySpend hooks are used
• Should be used on the client side (add 'use client' directive in Next.js)
• Only one instance is needed in your component tree
• When using with dynamic imports, ensure the provider wraps the dynamic component

Available Hooks

useAnyspendCreateOrder

Creates a new order in the Anyspend protocol. Handles address formatting and payload structure.

import { useAnyspendCreateOrder } from '@b3dotfun/anyspend-sdk';

function CreateOrder() {
  const { createOrder, isCreatingOrder } = useAnyspendCreateOrder({
    onSuccess: (data) => {
      console.log('Order created:', data);
    },
    onError: (error: Error | AnyspendApiError) => {
      // Handle API errors with proper typing
      if ('statusCode' in error) {
        console.error('API Error:', error.message, 'Status:', error.statusCode);
      } else {
        console.error('Client Error:', error.message);
      }
    },
  });

  const handleCreateOrder = async () => {
    createOrder({
      recipientAddress,
      orderType,
      srcChain,
      dstChain,
      srcToken,
      srcAmount,
      dstToken,
      expectedDstAmount,
    });
  };

  return (
    <button onClick={handleCreateOrder} disabled={isCreatingOrder}>
      Create Order
    </button>
  );
}

The hook provides proper error typing through AnyspendApiError interface:

type AnyspendApiError = {
  message: string;    // Error message from the API
  statusCode: number; // HTTP status code
  success: false;     // Always false for errors
  data: null;         // No data in error cases
};

Common API errors include:

• 400: Invalid input parameters (e.g., "dstTokenAddress must be native for Deposit order")
• 401: Unauthorized
• 404: Resource not found
• 500: Server error

useAnyspendChains

Fetches available chains for a given order type.

import { useAnyspendChains, OrderType } from '@b3dotfun/anyspend-sdk';

function ChainList() {
  const { data: chains, isLoading } = useAnyspendChains(OrderType.Deposit);
  // ...
}

useAnyspendOrderAndTransactions

Fetches and auto-refreshes order status and transaction details.

import { useAnyspendOrderAndTransactions } from '@b3dotfun/anyspend-sdk';

function OrderDetails({ orderId }) {
  const {
    orderAndTransactions,
    isLoadingOrderAndTransactions,
    getOrderAndTransactionsError,
    refetchOrderAndTransactions
  } = useAnyspendOrderAndTransactions(orderId);
  // ...
}

useAnyspendOrderHistory

Retrieves order history for one or more recipient addresses. Orders are automatically deduped and sorted by creation date (newest first).

import { useAnyspendOrderHistory } from '@b3dotfun/anyspend-sdk';

// Single address
function SingleAddressHistory({ recipientAddress }) {
  const {
    orderHistory,
    isLoadingOrderHistory,
    getOrderHistoryError,
    refetchOrderHistory
  } = useAnyspendOrderHistory(recipientAddress);
  // ...
}

// Multiple addresses
function MultiAddressHistory({ addresses }) {
  const {
    orderHistory,
    isLoadingOrderHistory,
    getOrderHistoryError,
    refetchOrderHistory
  } = useAnyspendOrderHistory(addresses);
  // ...
}

The hook will:

• Accept a single address or an array of addresses
• Automatically dedupe input addresses to avoid redundant API calls
• Combine and dedupe orders from all addresses
• Sort orders by creation date (newest first)

useAnyspendPrice

Fetches price/rate information for token swaps.

import { useAnyspendPrice } from '@b3dotfun/anyspend-sdk';

function PriceQuote({ srcChain, dstChain, srcToken, dstToken, amount }) {
  const {
    anyspendPrice,
    isLoadingAnyspendPrice,
    getAnyspendPriceError,
    refetchAnyspendPrice
  } = useAnyspendPrice(
    srcChain,
    dstChain,
    srcToken,
    dstToken,
    amount,
    true // isSrcInputDirty
  );
  // ...
}

useAnyspendTokens

Fetches available tokens for a specific chain.

import { useAnyspendTokens } from '@b3dotfun/anyspend-sdk';

function TokenList({ chainId }) {
  const { data: tokens, isLoading } = useAnyspendTokens(chainId);
  // ...
}

Utilities

formatTokenAmount

Formats token amounts with proper decimal places.

import { formatTokenAmount } from '@b3dotfun/anyspend-sdk';

const formattedAmount = formatTokenAmount(amount, decimals);

getStatusText

Converts order status to human-readable text.

import { getStatusText, OrderStatus } from '@b3dotfun/anyspend-sdk';

const statusText = getStatusText(OrderStatus.Ready);

getPaymentUrl

Generates payment URLs for Ethereum transactions.

import { getPaymentUrl } from '@b3dotfun/anyspend-sdk';

const url = getPaymentUrl(address, amount, 'ETH');

Types

The SDK includes TypeScript definitions for all its functionality. Key types include:

• OrderStatus
• OrderType
• ChainType
• Token
• Order
• DepositTransaction
• RelayTransaction
• ExecuteTransaction

Environment Variables

The SDK uses the following environment variable:

• ANYSPEND_BASE_URL: Base URL for the Anyspend API (defaults to development URL if not set)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

[Add your license information here]