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
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';
const YOUR_WALLET_PRIVATE_KEY = process.env.USER_PRIVATE_KEY;
async function main() {
try {
const response = await apiNow.execute(
'https://apinow.fun/api/endpoints/apinowfun/translate-TRANSLATE',
YOUR_WALLET_PRIVATE_KEY,
{
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