apinow-sdk 0.12.3 → 0.12.4

package/README.md

@@ -1,14 +1,15 @@
 # ApiNow SDK
 
-A TypeScript SDK for interacting with ApiNow endpoints, supporting Ethereum and Base chains. Designed to work in Node.js, browsers, and edge environments like Cloudflare Workers.
+A TypeScript SDK for interacting with ApiNow endpoints, supporting Ethereum and Base chains. This SDK simplifies payments by automatically handling `402 Payment Required` responses, including on-the-fly token swaps.
 
 ## Features
 
-- Multi-chain support (Ethereum, Base)
-- Native and ERC20 token transfers
-- Environment Agnostic: Uses global `fetch` for broad compatibility.
-- Optional RPC URL: Uses public RPCs by default, allows override.
-- TypeScript types for better development experience.
+- **Automatic x402 Payments**: Intercepts `402` responses to handle payment flows automatically.
+- **On-the-fly Token Swaps**: If you don't have the required payment token, the SDK can swap a common asset (like ETH, WETH, or USDC) to make the payment, powered by 0x.
+- **Flexible Pricing**: Supports endpoints that require a fixed token amount or a USD equivalent.
+- **Configurable Payment**: Prioritize which tokens you prefer to pay with.
+- **Multi-chain support**: Works with Ethereum and Base.
+- **Node.js Environment**: Designed to work in a Node.js environment.
 
 ## Installation
 
@@ -20,147 +21,132 @@ yarn add apinow-sdk
 
 ## Usage
 
-### Basic Example (Using Default RPCs)
+The primary way to use the SDK is with the `execute` method. It's a single call that handles all the complexity of API payments for you.
 
 ```typescript
 import apiNow from 'apinow-sdk';
 
+// The API endpoint you want to interact with.
 const ENDPOINT_URL = 'https://apinow.fun/api/endpoints/your-endpoint';
+
+// Your private key, securely stored (e.g., in an environment variable).
 const YOUR_WALLET_PRIVATE_KEY = '0x...'; 
 
-// 1. Get endpoint info (payment details)
-const info = await apiNow.info(ENDPOINT_URL);
-// info will contain: { requiredAmount, walletAddress, httpMethod, tokenAddress, chain }
-// Note: chain will be 'eth' or 'base'
-console.log('Payment required:', info);
-
-// 2. Send payment and get the API response in one step
-try {
-  const response = await apiNow.infoBuyResponse(
-    ENDPOINT_URL,
-    YOUR_WALLET_PRIVATE_KEY
-    // Optional: Add RPC URL override here if needed
-    // Optional: Add options like { fastMode: true } here (Note: fastMode currently has no effect)
-  );
-  console.log('API Response:', response);
-} catch (error) {
-  console.error('Operation failed:', error);
+async function main() {
+  try {
+    // The `execute` method handles everything automatically.
+    // If the API requires a payment (402), the SDK will:
+    // 1. Find the best token you hold to pay with.
+    // 2. If needed, swap a common asset (like ETH or USDC) to the required token.
+    // 3. Send the payment transaction.
+    // 4. Retry the original request with proof of payment.
+    const response = await apiNow.execute(
+      ENDPOINT_URL,
+      YOUR_WALLET_PRIVATE_KEY,
+      { // Optional: request options
+        method: 'POST',
+        data: { query: 'your-data' }
+      }
+    );
+
+    console.log('API Response:', response);
+  } catch (error) {
+    console.error('Operation failed:', error);
+  }
 }
+
+main();
 ```
 
-### Providing a Custom RPC URL
+## How It Works: Automatic Payments
 
-If you need to use a specific RPC node (e.g., for Base):
+When you call `execute`, the SDK makes a request to the endpoint. If the server responds with a `402 Payment Required` status, the SDK automatically performs the following steps:
 
-```typescript
-const CUSTOM_RPC_URL = 'https://mainnet.base.org';
+1.  **Parses Payment Options**: The `402` response contains a list of accepted payment options. This can be a single token (fixed price) or multiple tokens (USD equivalent price, e.g., "$5 of USDC" or "$5 of ETH").
+2.  **Checks Balances**: It checks your wallet balance for each of the accepted payment tokens.
+3.  **Prioritizes Payment**: It attempts to pay using your tokens in a preferred order (default: `['USDC', 'WETH', 'ETH']`).
+4.  **Swaps if Needed**: If you don't have any of the *required* tokens, the SDK will try to swap one of your preferred assets for the required one. For example, it can swap your USDC to pay with a different required token.
+5.  **Pays and Retries**: Once the payment transaction is sent, the SDK automatically retries the original API request, now with proof of payment.
 
-const response = await apiNow.infoBuyResponse(
-  ENDPOINT_URL,
-  YOUR_WALLET_PRIVATE_KEY,
-  CUSTOM_RPC_URL // Provide the RPC URL here
-);
-```
+## Configuration
 
-### Fast Mode
+You can customize the behavior of the `execute` method with the `opts` and `paymentConfig` parameters.
 
-*Note: `fastMode` is currently included for potential future use but does not affect Ethereum/Base transaction confirmation behavior in this version.* 
+### Request Options (`opts`)
 
-```typescript
-const response = await apiNow.infoBuyResponse(
-  ENDPOINT_URL,
-  YOUR_WALLET_PRIVATE_KEY,
-  undefined, // Use default RPC
-  { fastMode: true } // Option included, but no effect yet
-);
-```
-
-### Manual Payment (Separate Steps)
+Passed as the third argument to `execute`. This corresponds to `TxResponseOptions`.
 
-```typescript
-import apiNow from 'apinow-sdk';
-import { ethers } from 'ethers';
+-   `method`: The HTTP method for your request (e.g., `'GET'`, `'POST'`). Defaults to `'GET'`.
+-   `data`: The payload for your request. For `POST` requests, this is the JSON body. For `GET`, it's converted to query parameters.
 
-const ENDPOINT_URL = 'https://apinow.fun/api/endpoints/your-endpoint';
-const YOUR_WALLET_PRIVATE_KEY = '0x...';
-const YOUR_CUSTOM_RPC_URL = 'https://your-node.com'; // Optional
+### Payment Configuration (`paymentConfig`)
 
-// 1. Get Info
-const info = await apiNow.info(ENDPOINT_URL);
-const { requiredAmount, walletAddress, chain, tokenAddress } = info;
+Passed as the fourth argument to `execute`. This corresponds to `X402PaymentConfig`.
 
-// Convert requiredAmount (string) to bigint (wei)
-const amountBigInt = BigInt(requiredAmount);
+-   `preferredTokens`: An array of token symbols (e.g., `['USDC', 'WETH']`) that you prefer to pay with. The SDK will check your balance of these tokens first.
 
-// 2. Send Payment
-const txHash = await apiNow.buy(
-  walletAddress,
-  amountBigInt,
+```typescript
+await apiNow.execute(
+  ENDPOINT_URL,
   YOUR_WALLET_PRIVATE_KEY,
-  chain, // 'eth' or 'base'
-  YOUR_CUSTOM_RPC_URL, // Optional: override RPC
-  tokenAddress // Optional: specify ERC20 token if required
-  // fastMode param exists but is unused by handler
+  { method: 'POST', data: { /* ... */ } }, // opts
+  { preferredTokens: ['DAI', 'USDC'] }   // paymentConfig
 );
-console.log(`Payment sent: ${txHash}`);
+```
 
-// 3. Get API Response (add delay as needed)
-await new Promise(resolve => setTimeout(resolve, 5000)); // Example 5s delay
+## Legacy Flow (Backward Compatibility)
 
-const apiResponse = await apiNow.txResponse(
+For backward compatibility, the `infoBuyResponse` method is still available. It performs a less sophisticated multi-step payment process.
+
+```typescript
+const response = await apiNow.infoBuyResponse(
   ENDPOINT_URL,
-  txHash
+  YOUR_WALLET_PRIVATE_KEY
 );
-console.log('API Response:', apiResponse);
 ```
 
 ## API Reference
 
-### `info(endpoint: string): Promise<InfoResponse>`
-
-Gets payment requirement information about an ApiNow endpoint.
-
-### `buy(walletAddress: string, amount: bigint, userWalletPrivateKey: string, chain: 'eth' | 'base', rpcUrl?: string, tokenAddress?: string, fastMode?: boolean): Promise<string>`
-
-Sends the required payment transaction to the specified address.
-- `amount`: The required amount in the smallest unit (wei).
-- `userWalletPrivateKey`: The private key of the wallet sending the funds.
-- `chain`: The blockchain target ('eth' or 'base').
-- `rpcUrl` (Optional): Overrides the default public RPC URL.
-- `tokenAddress` (Optional): The contract address if paying with an ERC20 token.
-- `fastMode` (Optional): Parameter exists but currently has no effect.
-
-Returns the transaction hash.
-
-### `txResponse(endpoint: string, txHash: string, opts?: TxResponseOptions): Promise<any>`
+### `execute(endpoint, privateKey, opts?, paymentConfig?)`
+Handles a request and its potential payment in a single, automatic call. This is the recommended method.
 
-Fetches the final API response from the endpoint after a successful payment.
-- `txHash`: The hash of the payment transaction.
-- `opts` (Optional): Options like `{ method: 'POST', data: {...} }`.
+### `infoBuyResponse(endpoint, privateKey, rpcUrl?, opts?)`
+(Legacy) Combines `info`, `buy`, and `txResponse` into a single call.
 
-Returns the endpoint's API response.
+### `info(endpoint)`
+(Legacy) Gets payment requirement information from an endpoint.
 
-### `infoBuyResponse(endpoint: string, userWalletPrivateKey: string, rpcUrl?: string, opts?: TxResponseOptions & { fastMode?: boolean }): Promise<any>`
+### `buy(walletAddress, amount, privateKey, chain, ...)`
+(Legacy) Sends a payment transaction.
 
-Combines `info`, `buy`, and `txResponse` into a single call.
-- `userWalletPrivateKey`: The private key of the wallet sending the funds.
-- `rpcUrl` (Optional): Overrides the default public RPC URL for the payment.
-- `opts` (Optional): Contains `fastMode` boolean (currently no effect) and any `TxResponseOptions`.
-
-Returns the final API response.
+### `txResponse(endpoint, txHash, opts?)`
+(Legacy) Fetches the API response after a payment has been made manually.
 
 ## Types
 
 ```typescript
-// Defined in the SDK
-interface InfoResponse {
-  requiredAmount: string; // Amount in wei (string)
-  walletAddress: string;
-  httpMethod: string; 
-  tokenAddress?: string; // ERC20 address
+// Response from a 402 error
+interface X402PaymentInfo {
+  challenge: string;
   chain: 'eth' | 'base';
+  recipientAddress: string;
+  options: X402PaymentOption[];
+}
+
+// A single way to pay
+interface X402PaymentOption {
+  tokenAddress: string;
+  symbol: string;
+  amount: string;
+  decimals: number;
 }
 
+// Configuration for payments
+interface X402PaymentConfig {
+  preferredTokens?: string[];
+}
+
+// Options for the API request itself
 interface TxResponseOptions {
   method?: string; 
   data?: any;      
@@ -172,46 +158,68 @@ interface TxResponseOptions {
 - **Ethereum:** `https://rpc.ankr.com/eth`
 - **Base:** `https://mainnet.base.org`
 
-You can override these by providing the `rpcUrl` parameter to `buy` or `infoBuyResponse`.
-
 ## Error Handling
 
 The SDK throws descriptive errors for:
 - Invalid endpoint URLs or configurations.
 - RPC communication errors.
 - Transaction signing or sending failures.
-- Insufficient funds or token allowances.
-- Failures during API response fetching (`txResponse`).
+- Insufficient funds or failure to find a valid swap.
+- Failures during API response fetching.
 
 Wrap calls in `try...catch` blocks for robust error handling.
 
 ## Compatibility
 
-This SDK uses the standard Web `fetch` API and avoids Node.js-specific modules, making it compatible with:
-- Node.js (v18+ recommended for global fetch)
-- Browsers (modern)
-- Edge environments (Cloudflare Workers, Vercel Edge Functions, etc.)
+This SDK uses `node-fetch`, making it compatible with:
+- Node.js (v18+ recommended)
+
+It is NOT directly compatible with browsers or edge environments that do not provide a Node.js-compatible `fetch` API.
 
 ## License
 
 MIT
 
-Copyright (c) 2024 Your Name
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+## Examples
+
+This project includes a test server and a test runner to demonstrate various payment scenarios.
+
+1.  **Create a `.env` file** in the root of the project and add your wallet's private key:
+    ```
+    PRIVATE_KEY=your_private_key_here
+    ```
+
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+
+3.  **Start the test server:**
+    The test server simulates an API that requires different types of payments.
+    ```bash
+    node test/test-server.js
+    ```
+
+4.  **Run the test runner:**
+    In a separate terminal, run the test runner to execute a series of transactions against the test server.
+    ```bash
+    node test/test-runner.js
+    ```
+
+This will demonstrate:
+- Paying with USDC
+- Paying with a custom ERC20 token
+- Paying with a token priced in USDC
+- Fallback token payments
+- Handling various error conditions
+
+## Local Development
+
+1. **Build the project:**
+   ```bash
+   npm run build
+   ```
+
+This will compile the TypeScript source files into JavaScript in the `dist` directory.
+
+## Contributing

package/dist/index.d.ts

@@ -1,6 +1,8 @@
+import { Wallet } from 'ethers';
 interface TxResponseOptions {
     method?: string;
     data?: any;
+    signature?: string;
 }
 interface InfoResponse {
     requiredAmount: string;
@@ -10,10 +12,34 @@ interface InfoResponse {
     chain: 'eth' | 'base';
     decimals?: number;
 }
+interface X402PaymentOption {
+    tokenAddress: string;
+    symbol: string;
+    amount?: string;
+    usdAmount?: string;
+    decimals: number;
+}
+interface X402PaymentInfo {
+    challenge: string;
+    chain: 'eth' | 'base';
+    recipientAddress: string;
+    options: X402PaymentOption[];
+}
+interface X402PaymentConfig {
+    preferredTokens?: string[];
+    swapFromAssets?: {
+        symbol: string;
+        address: string;
+    }[];
+    slippagePercentage?: string;
+}
+declare function get0xSwapQuote(buyToken: string, sellToken: string, buyAmount: bigint, buyTokenDecimals: number, takerAddress: string, chain: 'eth' | 'base', slippagePercentage?: string): Promise<any>;
 declare class ApiNow {
     private handlers;
     info(endpoint: string): Promise<InfoResponse>;
     buy(walletAddress: string, amount: bigint, userWalletPrivateKey: string, chain: 'eth' | 'base', rpcUrl?: string, tokenAddress?: string, fastMode?: boolean): Promise<string>;
+    execute(endpoint: string, userWalletPrivateKey: string, opts?: TxResponseOptions, paymentConfig?: X402PaymentConfig): Promise<any>;
+    approve(wallet: Wallet, tokenAddress: string, spenderAddress: string, amount: bigint): Promise<string>;
     txResponse(endpoint: string, txHash: string, opts?: TxResponseOptions): Promise<any>;
     infoBuyResponse(endpoint: string, userWalletPrivateKey: string, rpcUrl?: string, opts?: TxResponseOptions & {
         fastMode?: boolean;
@@ -21,4 +47,5 @@ declare class ApiNow {
 }
 declare const apiNow: ApiNow;
 export default apiNow;
-export type { InfoResponse, TxResponseOptions };
+export { get0xSwapQuote };
+export type { InfoResponse, TxResponseOptions, X402PaymentInfo, X402PaymentOption, X402PaymentConfig };

package/dist/index.js

@@ -1,8 +1,22 @@
-import { ethers, Wallet, parseUnits, isAddress } from 'ethers';
-import fetch from 'node-fetch'; // Import node-fetch
+console.log('[sdk] SDK v1.1 loaded. This version includes header parsing and extensive logging.');
+import { ethers, Contract, Wallet, JsonRpcProvider, parseUnits, isAddress } from 'ethers';
+import fetch from 'node-fetch'; // Import node-fetch and its RequestInit
 // Default RPC URLs
 const DEFAULT_ETH_RPC = 'https://rpc.ankr.com/eth';
 const DEFAULT_BASE_RPC = 'https://mainnet.base.org';
+const NATIVE_TOKEN_ADDRESS = '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee';
+const CHAIN_CONFIG = {
+    '1': {
+        USDC: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+        WETH: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+        ETH: NATIVE_TOKEN_ADDRESS
+    },
+    '8453': {
+        USDC: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        WETH: '0x4200000000000000000000000000000000000006',
+        ETH: NATIVE_TOKEN_ADDRESS
+    }
+};
 // --- Helper function for fetch (Keep this) ---
 async function fetchJson(url, options) {
     console.error(`fetchJson (using node-fetch): Called with URL: ${url}`);
@@ -96,6 +110,343 @@ async function fetchJson(url, options) {
     console.error(`fetchJson: Successfully fetched and parsed JSON (first 500 chars): ${JSON.stringify(responseData).substring(0, 500)}`);
     return responseData;
 }
+// Helper to check ERC20 token balance
+async function getTokenBalance(provider, ownerAddress, tokenAddress) {
+    const abi = ["function balanceOf(address owner) view returns (uint256)"];
+    const contract = new Contract(tokenAddress, abi, provider);
+    try {
+        const balance = await contract.balanceOf(ownerAddress);
+        return balance;
+    }
+    catch (e) {
+        console.error(`[sdk] Could not get balance for token ${tokenAddress} (this is expected for invalid tokens in fallback tests). Error: ${e instanceof Error ? e.message : String(e)}`);
+        return 0n; // Return 0 if the token address is invalid or another error occurs
+    }
+}
+// Helper to check ERC20 token allowance
+async function checkAllowance(provider, ownerAddress, tokenAddress, spenderAddress) {
+    const abi = ["function allowance(address owner, address spender) view returns (uint256)"];
+    const contract = new Contract(tokenAddress, abi, provider);
+    const allowance = await contract.allowance(ownerAddress, spenderAddress);
+    return allowance;
+}
+// New helper for x402 flow
+async function fetchWithX402(url, options, api, // Pass in the ApiNow instance
+userWalletPrivateKey, paymentConfig = {}) {
+    const originalResponse = await fetch(url, options);
+    if (originalResponse.status !== 402) {
+        if (!originalResponse.ok) {
+            const errorBody = await originalResponse.text();
+            throw new Error(`HTTP Error ${originalResponse.status}: ${errorBody}`);
+        }
+        return originalResponse.json();
+    }
+    console.error("402 Payment Required. Handling payment...");
+    // --- FIX START: Parse the www-authenticate header instead of the body ---
+    const wwwAuthHeader = originalResponse.headers.get('www-authenticate');
+    console.log('[sdk] Raw www-authenticate header:', wwwAuthHeader);
+    if (!wwwAuthHeader) {
+        throw new Error('402 response is missing the www-authenticate header.');
+    }
+    const l402Match = wwwAuthHeader.match(/L402="([^"]+)"/);
+    console.log('[sdk] Regex match for L402 token:', l402Match);
+    if (!l402Match || !l402Match[1]) {
+        throw new Error('Could not parse L402 token from www-authenticate header.');
+    }
+    const l402Token = l402Match[1];
+    console.log('[sdk] Extracted L402 Base64 token:', l402Token);
+    let paymentInfo;
+    try {
+        const decodedToken = Buffer.from(l402Token, 'base64').toString('utf8');
+        console.log('[sdk] Decoded token (JSON string):', decodedToken);
+        const parsedToken = JSON.parse(decodedToken);
+        console.log('[sdk] Parsed token (JavaScript object):', JSON.stringify(parsedToken, null, 2));
+        // Ensure the parsed token matches the X402PaymentInfo interface
+        if (typeof parsedToken === 'object' && parsedToken !== null && 'challenge' in parsedToken && 'chain' in parsedToken && 'recipientAddress' in parsedToken && 'options' in parsedToken && Array.isArray(parsedToken.options)) {
+            paymentInfo = parsedToken;
+        }
+        else {
+            console.error('[sdk] Parsed token failed validation. Keys:', Object.keys(parsedToken));
+            throw new Error('Parsed L402 token is not in the expected X402PaymentInfo format (missing challenge, chain, recipientAddress, or options).');
+        }
+    }
+    catch (e) {
+        console.error('[sdk] Error during token decoding/parsing:', e);
+        throw new Error(`Failed to decode or parse L402 token: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    // --- FIX END ---
+    // --- NEW FIX START: Select RPC URL based on the parsed chain ---
+    const rpcUrl = paymentInfo.chain === 'base' ? DEFAULT_BASE_RPC : DEFAULT_ETH_RPC;
+    const provider = new JsonRpcProvider(rpcUrl);
+    const wallet = new Wallet(userWalletPrivateKey, provider);
+    console.log(`[sdk] Using RPC URL for chain "${paymentInfo.chain}": ${rpcUrl}`);
+    // --- NEW FIX END ---
+    const { challenge, chain, recipientAddress, options: paymentOptions } = paymentInfo;
+    let txHash;
+    // Define a preference order for payment tokens.
+    const preferredTokens = paymentConfig.preferredTokens || ['USDC', 'WETH']; // Default preference
+    const sortedOptions = [...paymentOptions].sort((a, b) => {
+        const aIndex = preferredTokens.indexOf(a.symbol);
+        const bIndex = preferredTokens.indexOf(b.symbol);
+        if (aIndex === -1 && bIndex === -1)
+            return 0;
+        if (aIndex === -1)
+            return 1;
+        if (bIndex === -1)
+            return -1;
+        return aIndex - bIndex;
+    });
+    const nativeSymbol = chain === 'base' ? 'ETH' : 'ETH'; // Could be more specific
+    const nativeOption = sortedOptions.find(o => o.symbol === nativeSymbol);
+    if (nativeOption) {
+        const nativeIndex = sortedOptions.indexOf(nativeOption);
+        sortedOptions.splice(nativeIndex, 1);
+        sortedOptions.push(nativeOption); // Always try native token last unless specified
+    }
+    for (const option of sortedOptions) {
+        const { tokenAddress, amount, decimals, symbol, usdAmount } = option;
+        let requiredAmount;
+        if (usdAmount) {
+            console.log(`[sdk] Option requires a USD value of ${usdAmount}. Fetching price for ${symbol}...`);
+            const tokenPriceInUsd = await getUsdcPriceForToken(tokenAddress, chain, decimals);
+            const requiredTokens = parseFloat(usdAmount) / tokenPriceInUsd;
+            console.log(`[sdk] Current price of ${symbol} is ~$${tokenPriceInUsd.toFixed(4)}. Required tokens: ${requiredTokens}`);
+            requiredAmount = parseUnits(requiredTokens.toString(), decimals);
+        }
+        else if (amount) {
+            requiredAmount = parseUnits(amount, decimals);
+        }
+        else {
+            console.warn(`[sdk] Skipping payment option for ${symbol} because it has no 'amount' or 'usdAmount'.`);
+            continue;
+        }
+        console.log(`[sdk] Checking balance for ${symbol} (${tokenAddress}). Required: ${requiredAmount.toString()}`);
+        let balance;
+        if (tokenAddress.toLowerCase() === '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee') {
+            balance = await provider.getBalance(wallet.address);
+        }
+        else {
+            balance = await getTokenBalance(provider, wallet.address, tokenAddress);
+        }
+        console.log(`[sdk] Found balance for ${symbol}: ${balance.toString()}`);
+        if (balance >= requiredAmount) {
+            console.log(`[sdk] Sufficient balance found for ${symbol}. Proceeding with payment.`);
+            txHash = await api.buy(recipientAddress, requiredAmount, userWalletPrivateKey, chain, rpcUrl, tokenAddress);
+            break;
+        }
+    }
+    if (!txHash) {
+        // --- Try to swap ---
+        console.log("No direct payment option possible. Attempting to find a swap.");
+        const chainId = chain === 'base' ? '8453' : '1';
+        const defaultSwapAssets = [
+            { symbol: 'USDC', address: CHAIN_CONFIG[chainId].USDC },
+            { symbol: 'WETH', address: CHAIN_CONFIG[chainId].WETH },
+            { symbol: 'ETH', address: CHAIN_CONFIG[chainId].ETH }
+        ];
+        const swapHierarchy = paymentConfig.swapFromAssets || defaultSwapAssets;
+        for (const targetOption of sortedOptions) {
+            for (const sourceAsset of swapHierarchy) {
+                try {
+                    const quote = await get0xSwapQuote(targetOption.tokenAddress, sourceAsset.address, 
+                    // --- FIX for USD amounts in swaps ---
+                    targetOption.usdAmount ?
+                        (await (async () => {
+                            console.log(`[sdk] Swap target requires a USD value of ${targetOption.usdAmount}. Fetching price for ${targetOption.symbol}...`);
+                            const tokenPriceInUsd = await getUsdcPriceForToken(targetOption.tokenAddress, chain, targetOption.decimals);
+                            const requiredTokens = parseFloat(targetOption.usdAmount) / tokenPriceInUsd;
+                            console.log(`[sdk] Swap target ${targetOption.symbol} price is ~$${tokenPriceInUsd.toFixed(4)}. Required tokens for swap: ${requiredTokens}`);
+                            return parseUnits(requiredTokens.toFixed(18), targetOption.decimals); // Use high precision for swap amount
+                        })()) :
+                        parseUnits(targetOption.amount, targetOption.decimals), // Use non-null assertion for amount
+                    // --- End FIX ---
+                    targetOption.decimals, wallet.address, chain, paymentConfig.slippagePercentage);
+                    const buyAmount = BigInt(quote.buyAmount);
+                    let cost;
+                    let sourceBalance;
+                    if (sourceAsset.address === NATIVE_TOKEN_ADDRESS) {
+                        if (!quote.transaction || !quote.transaction.gasPrice || !quote.transaction.gas) {
+                            throw new Error('0x quote response for native asset swap is missing transaction details (gas/gasPrice).');
+                        }
+                        cost = BigInt(quote.sellAmount) + (BigInt(quote.transaction.gasPrice) * BigInt(quote.transaction.gas)); // Correctly reference gasPrice and gas
+                        sourceBalance = await provider.getBalance(wallet.address);
+                    }
+                    else {
+                        cost = BigInt(quote.sellAmount);
+                        sourceBalance = await getTokenBalance(provider, wallet.address, sourceAsset.address);
+                        // Check allowance for the 0x spender contract and approve if necessary
+                        const allowance = await checkAllowance(provider, wallet.address, sourceAsset.address, quote.allowanceTarget);
+                        if (allowance < cost) {
+                            console.log(`Insufficient allowance for ${sourceAsset.symbol}. Approving ${quote.allowanceTarget} now...`);
+                            const approveTxHash = await api.approve(wallet, sourceAsset.address, quote.allowanceTarget, cost);
+                            console.log(`Approval transaction sent: ${approveTxHash}. Waiting for confirmation...`);
+                            const approveReceipt = await provider.waitForTransaction(approveTxHash);
+                            if (!approveReceipt || approveReceipt.status === 0) {
+                                throw new Error(`Approval transaction for ${sourceAsset.symbol} failed.`);
+                            }
+                            console.log('✅ Approval confirmed.');
+                        }
+                    }
+                    if (sourceBalance >= cost) {
+                        console.log(`Found affordable swap: ${sourceAsset.symbol} -> ${targetOption.symbol}.`);
+                        console.log('--- Full 0x Quote Response ---');
+                        console.log(JSON.stringify(quote, null, 2));
+                        console.log('-----------------------------');
+                        // Execute Swap
+                        const swapTx = {
+                            to: quote.transaction.to,
+                            data: quote.transaction.data,
+                            value: quote.transaction.value,
+                            gasPrice: quote.transaction.gasPrice,
+                            gasLimit: quote.transaction.gas, // Add gasLimit from quote
+                            nonce: await provider.getTransactionCount(wallet.address, 'latest'),
+                            chainId: parseInt(chainId),
+                        };
+                        console.log("Sending swap transaction...");
+                        const signedSwapTx = await wallet.signTransaction(swapTx);
+                        const swapTxHash = await provider.send('eth_sendRawTransaction', [signedSwapTx]);
+                        console.log(`Swap transaction sent: ${swapTxHash}. Waiting for confirmation...`);
+                        const swapReceipt = await provider.waitForTransaction(swapTxHash);
+                        if (!swapReceipt || swapReceipt.status === 0) {
+                            throw new Error(`Swap transaction failed: ${swapTxHash}`);
+                        }
+                        console.log('Swap transaction confirmed.');
+                        // Execute Payment
+                        console.log(`Swap successful. Proceeding with final payment.`);
+                        txHash = await api.buy(recipientAddress, buyAmount, // Use the amount from the swap quote
+                        userWalletPrivateKey, chain, rpcUrl, targetOption.tokenAddress);
+                        break; // Exit the source asset loop
+                    }
+                }
+                catch (error) {
+                    console.error(`Could not get swap quote for ${sourceAsset.symbol} -> ${targetOption.symbol}:`, error instanceof Error ? error.message : String(error));
+                    continue; // Try next source asset
+                }
+            }
+            if (txHash)
+                break; // Exit the target option loop
+        }
+        if (!txHash) {
+            throw new Error("Could not find a valid payment or swap option.");
+        }
+    }
+    console.error(`Payment transaction sent: ${txHash}. Waiting for confirmation...`);
+    const paymentReceipt = await provider.waitForTransaction(txHash);
+    if (!paymentReceipt || paymentReceipt.status === 0) {
+        throw new Error(`Final payment transaction failed: ${txHash}`);
+    }
+    console.log('Final payment transaction confirmed.');
+    const signature = await wallet.signMessage(challenge);
+    const retryOptions = { ...options };
+    retryOptions.headers['Authorization'] = `X402 ${txHash}:${signature}`;
+    console.error(`Retrying request to ${url} with payment proof.`);
+    const finalResponse = await fetch(url, retryOptions);
+    if (!finalResponse.ok) {
+        const errorBody = await finalResponse.text();
+        throw new Error(`API request failed after payment: ${errorBody}`);
+    }
+    return finalResponse.json();
+}
+async function get0xSwapQuote(buyToken, sellToken, buyAmount, buyTokenDecimals, takerAddress, chain, slippagePercentage = '0.01' // Default 1% slippage
+) {
+    const apiUrl = `https://api.0x.org`;
+    const chainId = chain === 'base' ? '8453' : '1';
+    const apiKey = process.env.ZERO_X_API_KEY;
+    if (!apiKey) {
+        throw new Error('ZERO_X_API_KEY is not set in the .env file. Please get a free key from https://dashboard.0x.org/apps');
+    }
+    const headers = {
+        '0x-api-key': apiKey,
+        '0x-version': 'v2'
+    };
+    // Step 1: Get a spot price by making a "reverse" lookup.
+    // We sell a nominal amount of the buyToken to get a price in terms of the sellToken.
+    const nominalSellAmount = parseUnits('1', buyTokenDecimals);
+    const priceParams = new URLSearchParams({
+        chainId: chainId,
+        buyToken: sellToken, // Swapped for reverse lookup
+        sellToken: buyToken, // Swapped for reverse lookup
+        sellAmount: nominalSellAmount.toString(),
+        taker: takerAddress,
+    }).toString();
+    const priceUrl = `${apiUrl}/swap/permit2/price?${priceParams}`;
+    console.log(`[sdk] Fetching 0x spot price with reverse lookup: ${priceUrl}`);
+    const priceResponse = await fetch(priceUrl, { headers });
+    if (!priceResponse.ok) {
+        const errorBody = await priceResponse.text();
+        console.error(`[sdk] Full 0x API spot price error response:`, errorBody);
+        throw new Error(`Failed to get 0x spot price: ${errorBody}`);
+    }
+    const priceData = (await priceResponse.json());
+    if (!priceData.buyAmount || !priceData.sellAmount || BigInt(priceData.sellAmount) === 0n) {
+        throw new Error('Could not determine a valid price for the swap. This might be due to low liquidity.');
+    }
+    // Step 2: Calculate the required sellAmount based on the reverse price quote.
+    // The reverse price gives us a ratio of sellToken per buyToken.
+    // sellAmount = buyAmount * (priceData.buyAmount / priceData.sellAmount)
+    const estimatedSellAmount = (buyAmount * BigInt(priceData.buyAmount)) / BigInt(priceData.sellAmount);
+    // Add a slippage buffer to the sell amount to ensure the trade goes through.
+    const slippageFactor = 1 + parseFloat(slippagePercentage);
+    const finalSellAmount = BigInt(Math.ceil(Number(estimatedSellAmount) * slippageFactor));
+    // Step 3: Get the firm quote with the estimated sellAmount.
+    const quoteParams = new URLSearchParams({
+        chainId: chainId,
+        buyToken: buyToken,
+        sellToken: sellToken,
+        sellAmount: finalSellAmount.toString(),
+        taker: takerAddress,
+    }).toString();
+    const quoteUrl = `${apiUrl}/swap/permit2/quote?${quoteParams}`;
+    console.error(`Fetching 0x firm quote: ${quoteUrl}`);
+    const response = await fetch(quoteUrl, { headers });
+    if (!response.ok) {
+        const errorBody = await response.text();
+        console.error(`[sdk] Full 0x API quote error response for ${quoteUrl}:`, errorBody);
+        throw new Error(`Failed to get 0x quote: ${errorBody}`);
+    }
+    return response.json();
+}
+// --- New helper to get the USDC price of a token ---
+async function getUsdcPriceForToken(tokenAddress, chain, tokenDecimals) {
+    if (tokenAddress.toLowerCase() === CHAIN_CONFIG[chain === 'base' ? '8453' : '1'].USDC.toLowerCase()) {
+        return 1.0; // USDC is always 1.0 USD
+    }
+    const apiUrl = `https://api.0x.org`;
+    const chainId = chain === 'base' ? '8453' : '1';
+    const apiKey = process.env.ZERO_X_API_KEY;
+    if (!apiKey) {
+        throw new Error('ZERO_X_API_KEY is not set in the .env file for price lookup.');
+    }
+    const headers = {
+        '0x-api-key': apiKey,
+        '0x-version': 'v2'
+    };
+    const nominalSellAmount = parseUnits('1', tokenDecimals).toString();
+    // We're buying USDC by selling one full unit of the token to find its price.
+    const priceParams = new URLSearchParams({
+        chainId: chainId,
+        buyToken: CHAIN_CONFIG[chainId].USDC,
+        sellToken: tokenAddress,
+        sellAmount: nominalSellAmount,
+    }).toString();
+    const priceUrl = `${apiUrl}/swap/permit2/price?${priceParams}`;
+    console.log(`[sdk] Fetching USDC price for ${tokenAddress} via 0x: ${priceUrl}`);
+    const priceResponse = await fetch(priceUrl, { headers });
+    if (!priceResponse.ok) {
+        const errorBody = await priceResponse.text();
+        throw new Error(`Failed to get 0x price for ${tokenAddress}: ${errorBody}`);
+    }
+    const priceData = (await priceResponse.json());
+    if (!priceData.buyAmount) {
+        throw new Error(`Invalid price response from 0x API: ${JSON.stringify(priceData)}`);
+    }
+    // The buyAmount is the amount of USDC (6 decimals) we get for 1 full unit of the sellToken.
+    const price = parseFloat(ethers.formatUnits(priceData.buyAmount, 6));
+    if (isNaN(price) || price <= 0) {
+        throw new Error(`Could not determine a valid price from 0x API response.`);
+    }
+    return price;
+}
 // --- Helper function for RPC calls (Keep this) ---
 async function sendJsonRpc(rpcUrl, method, params) {
     const response = await fetch(rpcUrl, {
@@ -123,14 +474,12 @@ async function sendJsonRpc(rpcUrl, method, params) {
 class EthereumHandler {
     async buy(walletAddress, amount, userWalletPrivateKey, chain, rpcUrl, tokenAddress) {
         const rpc = rpcUrl || (chain === 'base' ? DEFAULT_BASE_RPC : DEFAULT_ETH_RPC);
+        const provider = new JsonRpcProvider(rpc);
+        const wallet = new Wallet(userWalletPrivateKey, provider);
         if (!walletAddress || !isAddress(walletAddress)) {
             throw new Error('Invalid recipient wallet address');
         }
-        const wallet = new Wallet(userWalletPrivateKey);
-        const senderAddress = wallet.address;
         try {
-            const nonce = await sendJsonRpc(rpc, 'eth_getTransactionCount', [senderAddress, 'latest']);
-            const feeData = await sendJsonRpc(rpc, 'eth_gasPrice', []);
             let txRequest;
             if (tokenAddress) {
                 if (!isAddress(tokenAddress)) {
@@ -141,27 +490,21 @@ class EthereumHandler {
                 const data = iface.encodeFunctionData("transfer", [walletAddress, amount]);
                 txRequest = {
                     to: tokenAddress,
-                    nonce: parseInt(nonce, 16),
-                    gasPrice: feeData,
-                    gasLimit: 100000,
                     data: data,
-                    chainId: (await sendJsonRpc(rpc, 'eth_chainId', [])),
+                    value: 0
                 };
             }
             else {
                 txRequest = {
                     to: walletAddress,
                     value: amount,
-                    nonce: parseInt(nonce, 16),
-                    gasPrice: feeData,
-                    gasLimit: 21000,
-                    chainId: (await sendJsonRpc(rpc, 'eth_chainId', [])),
                 };
             }
-            const signedTx = await wallet.signTransaction(txRequest);
-            const txHash = await sendJsonRpc(rpc, 'eth_sendRawTransaction', [signedTx]);
-            console.error(`Transaction sent: ${txHash}. Confirmation check not implemented.`);
-            return txHash;
+            const txResponse = await wallet.sendTransaction(txRequest);
+            console.error(`Transaction sent: ${txResponse.hash}. Waiting for confirmation...`);
+            await txResponse.wait();
+            console.error(`Transaction confirmed: ${txResponse.hash}`);
+            return txResponse.hash;
         }
         catch (error) {
             console.error('Detailed ETH error:', error);
@@ -198,6 +541,35 @@ class ApiNow {
         }
         return handler.buy(walletAddress, amount, userWalletPrivateKey, chain, rpcUrl, tokenAddress);
     }
+    async execute(endpoint, userWalletPrivateKey, opts = {}, paymentConfig = {}) {
+        console.error(`Executing request for endpoint: ${endpoint}`);
+        const url = new URL(endpoint);
+        const method = (opts.method || 'GET').toUpperCase();
+        const fetchOptions = {
+            method: method,
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': '*/*',
+            },
+        };
+        if (opts.data) {
+            if (method === 'GET' || method === 'HEAD') {
+                const params = new URLSearchParams(opts.data);
+                params.forEach((value, key) => url.searchParams.append(key, value));
+            }
+            else {
+                fetchOptions.body = JSON.stringify(opts.data);
+            }
+        }
+        return fetchWithX402(url.toString(), fetchOptions, this, userWalletPrivateKey, paymentConfig);
+    }
+    async approve(wallet, tokenAddress, spenderAddress, amount) {
+        const abi = ["function approve(address spender, uint256 amount)"];
+        const contract = new Contract(tokenAddress, abi, wallet);
+        const tx = await contract.approve(spenderAddress, amount);
+        await tx.wait();
+        return tx.hash;
+    }
     async txResponse(endpoint, txHash, opts = {}) {
         console.error(`txResponse: Called with endpoint: ${endpoint}, txHash: ${txHash}, opts:`, JSON.stringify(opts, null, 2));
         if (!endpoint || typeof endpoint !== 'string') {
@@ -225,6 +597,10 @@ class ApiNow {
             },
             // body is set conditionally below
         };
+        if (opts.signature) {
+            fetchOptions.headers['X-Signature'] = opts.signature;
+            console.error(`txResponse: Included signature in X-Signature header.`);
+        }
         if (method === 'GET' || method === 'HEAD') {
             // --- GET/HEAD: Append data as query params ---
             if (opts.data && typeof opts.data === 'object' && Object.keys(opts.data).length > 0) {
@@ -290,6 +666,9 @@ class ApiNow {
         console.error(`Attempting payment: Chain=${chain}, To=${walletAddress}, Amount=${amountBigInt.toString()}, Token=${tokenAddress || 'Native'}`);
         const txHash = await this.buy(walletAddress, amountBigInt, userWalletPrivateKey, chain, rpcUrl, tokenAddress, opts.fastMode);
         console.error(`Transaction sent: ${txHash}`);
+        const wallet = new Wallet(userWalletPrivateKey);
+        const signature = await wallet.signMessage(txHash);
+        console.error(`Generated signature for txHash ${txHash}: ${signature}`);
         if (!opts.fastMode) {
             await new Promise(resolve => setTimeout(resolve, 3000));
         }
@@ -300,7 +679,8 @@ class ApiNow {
         // Create specific options for txResponse
         const txResponseOpts = {
             method: info.httpMethod || 'POST', // Use the method from info, default to POST
-            data: opts.data // Pass the original data payload intended for the API
+            data: opts.data, // Pass the original data payload intended for the API
+            signature: signature
         };
         // Call txResponse with the tailored options
         return this.txResponse(endpoint, txHash, txResponseOpts);
@@ -308,3 +688,4 @@ class ApiNow {
 }
 const apiNow = new ApiNow();
 export default apiNow;
+export { get0xSwapQuote }; // Export for testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apinow-sdk",
-  "version": "0.12.3",
+  "version": "0.12.4",
   "description": "ApiNow SDK · The endpoint vending machine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,7 +24,6 @@
     "apinow-sdk": "^0.11.19",
     "body-parser": "^2.2.0",
     "ethers": "^6.13.5",
-    "express": "^5.1.0",
     "node-fetch": "^3.3.2"
   },
   "devDependencies": {