@agentfish/sdk

Smart wallet SDK for AI agents. Automatic x402 payment handling for seamless AI-powered transactions.

Installation

npm install @agentfish/sdk
# or
pnpm add @agentfish/sdk

Quick Start

import { AgentFish } from '@agentfish/sdk';

const agent = new AgentFish({
  apiKey: 'agentfish_live_abc123...',
  walletId: 'your-wallet-id',
});

// Automatic x402 payment handling
const response = await agent.fetch('https://api.example.com/ai-endpoint');
const data = await response.json();
// If the API returns 402 Payment Required, AgentFish pays automatically!

Features

• Automatic x402 Payments - Detects 402 responses and pays automatically
• Wallet Management - Check balance, limits, and transaction history
• Spending Controls - Per-transaction and daily limits enforced
• Non-Custodial - Your keys are securely managed, never exposed

API Reference

Constructor

const agent = new AgentFish({
  apiKey: string;        // Your AgentFish API key
  walletId: string;      // Your wallet ID
  baseUrl?: string;      // API URL (default: https://api.agentfi.sh)
  debug?: boolean;       // Enable debug logging
});

Methods

fetch(url, options?)

Drop-in replacement for fetch() with automatic x402 payment handling.

const response = await agent.fetch('https://api.example.com/data', {
  method: 'POST',
  body: JSON.stringify({ prompt: 'Hello AI' }),
  
  // AgentFish-specific options:
  skipPayment: false,    // Skip automatic payment (default: false)
  maxPayment: 1.0,       // Max payment in USDC (throws if exceeded)
  metadata: { ... },     // Attach metadata to payment
});

fetchJson<T>(url, options?)

Convenience method that parses JSON response.

const data = await agent.fetchJson<{ result: string }>('https://api.example.com/data');
console.log(data.result);

pay(amount, merchant, merchantAddress, metadata?)

Execute a manual payment.

const result = await agent.pay(
  0.50,                              // Amount in USDC
  'https://api.example.com',         // Merchant identifier
  'So1ana...Address',                // Recipient Solana address
  { requestId: '123' }               // Optional metadata
);

console.log(result.signature); // Solana transaction signature

getWallet()

Get current wallet information.

const wallet = await agent.getWallet();
console.log(wallet.address);    // Wallet address
console.log(wallet.balance);    // Balance in micro-USDC
console.log(wallet.dailyLimit); // Daily spending limit

getBalance()

Get formatted balance information.

const balance = await agent.getBalance();
console.log(balance.balance);        // Current balance in USDC
console.log(balance.dailyRemaining); // Remaining daily limit in USDC
console.log(balance.perTxLimit);     // Per-transaction limit in USDC

getPayments(limit?)

Get recent payment history.

const payments = await agent.getPayments(10);
payments.forEach(p => {
  console.log(`${p.amount} USDC to ${p.merchant} - ${p.status}`);
});

Error Handling

import { 
  AgentFishError,
  AuthenticationError,
  PaymentError,
  PaymentLimitError,
  InsufficientBalanceError,
} from '@agentfish/sdk';

try {
  await agent.fetch('https://api.example.com/expensive');
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    console.log(`Need ${error.required} USDC, have ${error.balance} USDC`);
  } else if (error instanceof PaymentLimitError) {
    console.log(`Payment of ${error.requested} exceeds limit of ${error.limit}`);
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  }
}

Utilities

Helper functions for working with x402 and USDC amounts:

import { 
  fromMicroUsdc,      // Convert micro-USDC to USDC
  toMicroUsdc,        // Convert USDC to micro-USDC
  isPaymentRequired,  // Check if response is 402
  parseX402Response,  // Parse x402 payment requirements
} from '@agentfish/sdk';

// Convert amounts
fromMicroUsdc(1_000_000);  // 1.0 (USDC)
toMicroUsdc(1.5);          // 1500000n (micro-USDC)

// Check response status
if (isPaymentRequired(response)) {
  const requirements = parseX402Response(response);
  console.log(requirements.amount, requirements.address);
}

Example: AI Chat Integration

import { AgentFish } from '@agentfish/sdk';

const agent = new AgentFish({
  apiKey: process.env.AGENTFISH_API_KEY!,
  walletId: process.env.AGENTFISH_WALLET_ID!,
});

async function chat(message: string) {
  const response = await agent.fetchJson<{ reply: string }>(
    'https://ai-api.example.com/chat',
    {
      method: 'POST',
      body: JSON.stringify({ message }),
      maxPayment: 0.10, // Cap at $0.10 per request
    }
  );
  
  return response.reply;
}

// Usage
const reply = await chat('What is the meaning of life?');
console.log(reply);
// Payment handled automatically if the API charges!

Development

# Build
pnpm nx build @agentfish/sdk

# Test
pnpm nx test @agentfish/sdk

# Type check
pnpm nx typecheck @agentfish/sdk

License

MIT