apinow-sdk

ApiNow SDK

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

• 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.
• Endpoint Discovery: Includes a search method to find endpoints semantically.
• 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

npm install apinow-sdk
# or
yarn add apinow-sdk

Quick Example

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.

import apiNow from 'apinow-sdk';

// Your private key, securely stored (e.g., in an environment variable).
const YOUR_WALLET_PRIVATE_KEY = process.env.USER_PRIVATE_KEY; 

async function main() {
  try {
    // The `execute` method handles everything automatically.
    // If the API requires a payment (402), the SDK will find the best
    // token you hold, swap if necessary, send the payment, and retry
    // the original request with proof of payment.
    const response = await apiNow.execute(
      'https://apinow.fun/api/endpoints/apinowfun/translate-TRANSLATE',
      YOUR_WALLET_PRIVATE_KEY,
      { // Optional: request options
        method: 'POST',
        data: { 
            text: 'Hello world',
            selectedLanguage: 'es'
        }
      }
    );

    console.log('API Response:', response);
  } catch (error) {
    console.error('Operation failed:', error);
  }
}

main();

For a complete, runnable example, see example.js.

How It Works: Automatic Payments

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:

• Parses Payment Options: The 402 response contains a list of accepted payment options.
• Checks Balances: It checks your wallet balance for each of the accepted payment tokens.
• Prioritizes Payment: It attempts to pay using your tokens in a preferred order (default: ['USDC', 'WETH', 'ETH']).
• 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.
• Pays and Retries: Once the payment transaction is sent, the SDK automatically retries the original API request, now with proof of payment.

API Reference

execute(endpoint, privateKey, opts?, paymentConfig?)

Handles a request and its potential payment in a single, automatic call. This is the recommended method.

search(params, privateKey, paymentConfig?)

Performs a semantic search for endpoints.

info(endpointUrl)

Retrieves public, detailed information about an endpoint.

Default RPC URLs

• Ethereum: https://rpc.ankr.com/eth
• Base: https://mainnet.base.org

Error Handling

The SDK throws descriptive errors for:

• Invalid endpoint URLs or configurations.
• RPC communication errors.
• Transaction signing or sending failures.
• 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 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