@ottocode/ai-sdk 0.1.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ottocode/ai-sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./providers": "./src/providers/index.ts",
+    "./types": "./src/types.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.0",
+    "@ai-sdk/google": "^3.0.0",
+    "@ai-sdk/openai": "^3.0.0",
+    "@ai-sdk/openai-compatible": "^2.0.0",
+    "@solana/web3.js": "^1.98.0",
+    "bs58": "^6.0.0",
+    "tweetnacl": "^1.0.3",
+    "x402": "^1.1.0"
+  },
+  "peerDependencies": {
+    "ai": ">=6.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,43 @@
+import { Keypair } from '@solana/web3.js';
+import bs58 from 'bs58';
+import nacl from 'tweetnacl';
+import type { SetuAuth } from './types.ts';
+
+export interface WalletContext {
+  keypair: Keypair;
+  walletAddress: string;
+  privateKeyBytes: Uint8Array;
+}
+
+export function createWalletContext(auth: SetuAuth): WalletContext {
+  const privateKeyBytes = bs58.decode(auth.privateKey);
+  const keypair = Keypair.fromSecretKey(privateKeyBytes);
+  const walletAddress = keypair.publicKey.toBase58();
+  return { keypair, walletAddress, privateKeyBytes };
+}
+
+export function signNonce(nonce: string, secretKey: Uint8Array): string {
+  const data = new TextEncoder().encode(nonce);
+  const signature = nacl.sign.detached(data, secretKey);
+  return bs58.encode(signature);
+}
+
+export function buildWalletHeaders(ctx: WalletContext): Record<string, string> {
+  const nonce = Date.now().toString();
+  const signature = signNonce(nonce, ctx.privateKeyBytes);
+  return {
+    'x-wallet-address': ctx.walletAddress,
+    'x-wallet-nonce': nonce,
+    'x-wallet-signature': signature,
+  };
+}
+
+export function getPublicKeyFromPrivate(privateKey: string): string | null {
+  try {
+    const privateKeyBytes = bs58.decode(privateKey);
+    const keypair = Keypair.fromSecretKey(privateKeyBytes);
+    return keypair.publicKey.toBase58();
+  } catch {
+    return null;
+  }
+}

package/src/balance.ts

@@ -0,0 +1,109 @@
+import bs58 from 'bs58';
+import { Keypair } from '@solana/web3.js';
+import type { SetuAuth, BalanceResponse, WalletUsdcBalance } from './types.ts';
+import { signNonce } from './auth.ts';
+
+const DEFAULT_BASE_URL = 'https://api.setu.ottocode.io';
+const DEFAULT_RPC_URL = 'https://api.mainnet-beta.solana.com';
+const USDC_MINT_MAINNET = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const USDC_MINT_DEVNET = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU';
+
+function trimTrailingSlash(url: string) {
+  return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+
+export async function fetchBalance(
+  auth: SetuAuth,
+  baseURL?: string,
+): Promise<BalanceResponse | null> {
+  try {
+    const privateKeyBytes = bs58.decode(auth.privateKey);
+    const keypair = Keypair.fromSecretKey(privateKeyBytes);
+    const walletAddress = keypair.publicKey.toBase58();
+    const url = trimTrailingSlash(baseURL ?? DEFAULT_BASE_URL);
+
+    const nonce = Date.now().toString();
+    const signature = signNonce(nonce, privateKeyBytes);
+
+    const response = await fetch(`${url}/v1/balance`, {
+      headers: {
+        'x-wallet-address': walletAddress,
+        'x-wallet-nonce': nonce,
+        'x-wallet-signature': signature,
+      },
+    });
+
+    if (!response.ok) return null;
+
+    const data = (await response.json()) as {
+      wallet_address: string;
+      balance_usd: number;
+      total_spent: number;
+      total_topups: number;
+      request_count: number;
+      created_at?: string;
+      last_request?: string;
+    };
+
+    return {
+      walletAddress: data.wallet_address,
+      balance: data.balance_usd,
+      totalSpent: data.total_spent,
+      totalTopups: data.total_topups,
+      requestCount: data.request_count,
+      createdAt: data.created_at,
+      lastRequest: data.last_request,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function fetchWalletUsdcBalance(
+  auth: SetuAuth,
+  network: 'mainnet' | 'devnet' = 'mainnet',
+): Promise<WalletUsdcBalance | null> {
+  try {
+    const privateKeyBytes = bs58.decode(auth.privateKey);
+    const keypair = Keypair.fromSecretKey(privateKeyBytes);
+    const walletAddress = keypair.publicKey.toBase58();
+    const rpcUrl = network === 'devnet' ? 'https://api.devnet.solana.com' : DEFAULT_RPC_URL;
+    const usdcMint = network === 'devnet' ? USDC_MINT_DEVNET : USDC_MINT_MAINNET;
+
+    const response = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'getTokenAccountsByOwner',
+        params: [walletAddress, { mint: usdcMint }, { encoding: 'jsonParsed' }],
+      }),
+    });
+
+    if (!response.ok) return null;
+
+    const data = (await response.json()) as {
+      result?: {
+        value?: Array<{
+          account: {
+            data: {
+              parsed: {
+                info: { tokenAmount: { uiAmount: number } };
+              };
+            };
+          };
+        }>;
+      };
+    };
+
+    let totalUsdcBalance = 0;
+    for (const account of data.result?.value ?? []) {
+      totalUsdcBalance += account.account.data.parsed.info.tokenAmount.uiAmount ?? 0;
+    }
+
+    return { walletAddress, usdcBalance: totalUsdcBalance, network };
+  } catch {
+    return null;
+  }
+}

package/src/cache.ts

@@ -0,0 +1,159 @@
+import type { AnthropicCacheConfig, AnthropicCachePlacement } from './types.ts';
+
+interface MessageBlock {
+  type: string;
+  cache_control?: { type: string };
+  [key: string]: unknown;
+}
+
+interface Message {
+  role: string;
+  content: unknown;
+  [key: string]: unknown;
+}
+
+interface ParsedBody {
+  system?: MessageBlock[];
+  messages?: Message[];
+  [key: string]: unknown;
+}
+
+const DEFAULT_CONFIG: Required<Omit<AnthropicCacheConfig, 'transform'>> = {
+  strategy: 'auto',
+  systemBreakpoints: 1,
+  messageBreakpoints: 1,
+  systemPlacement: 'first',
+  messagePlacement: 'last',
+  cacheType: 'ephemeral',
+};
+
+function resolveConfig(config?: AnthropicCacheConfig): Required<Omit<AnthropicCacheConfig, 'transform'>> & { transform?: AnthropicCacheConfig['transform'] } {
+  if (!config) return { ...DEFAULT_CONFIG };
+  return {
+    strategy: config.strategy ?? DEFAULT_CONFIG.strategy,
+    systemBreakpoints: config.systemBreakpoints ?? DEFAULT_CONFIG.systemBreakpoints,
+    messageBreakpoints: config.messageBreakpoints ?? DEFAULT_CONFIG.messageBreakpoints,
+    systemPlacement: config.systemPlacement ?? DEFAULT_CONFIG.systemPlacement,
+    messagePlacement: config.messagePlacement ?? DEFAULT_CONFIG.messagePlacement,
+    cacheType: config.cacheType ?? DEFAULT_CONFIG.cacheType,
+    transform: config.transform,
+  };
+}
+
+function shouldCacheAtIndex(
+  index: number,
+  total: number,
+  maxBreakpoints: number,
+  placement: AnthropicCachePlacement,
+): boolean {
+  if (maxBreakpoints <= 0) return false;
+
+  switch (placement) {
+    case 'first': {
+      return index < maxBreakpoints;
+    }
+    case 'last': {
+      const startFrom = total - maxBreakpoints;
+      return index >= startFrom && index < total;
+    }
+    case 'all': {
+      return true;
+    }
+  }
+}
+
+function injectCacheOnBlocks(
+  blocks: MessageBlock[],
+  maxBreakpoints: number,
+  placement: AnthropicCachePlacement,
+  cacheType: string,
+): { blocks: MessageBlock[]; used: number } {
+  let used = 0;
+  const eligible = blocks.map((_, i) => shouldCacheAtIndex(i, blocks.length, maxBreakpoints, placement));
+  const result = blocks.map((block, i) => {
+    if (block.cache_control) return block;
+    if (used < maxBreakpoints && eligible[i]) {
+      used++;
+      return { ...block, cache_control: { type: cacheType } };
+    }
+    return block;
+  });
+  return { blocks: result, used };
+}
+
+export function addAnthropicCacheControl(
+  parsed: ParsedBody,
+  config?: AnthropicCacheConfig,
+): ParsedBody {
+  const resolved = resolveConfig(config);
+
+  if (resolved.strategy === false) return parsed;
+
+  if (resolved.strategy === 'manual') return parsed;
+
+  if (resolved.strategy === 'custom' && resolved.transform) {
+    return resolved.transform(parsed as Record<string, unknown>) as ParsedBody;
+  }
+
+  let systemUsed = 0;
+
+  if (parsed.system && Array.isArray(parsed.system)) {
+    const result = injectCacheOnBlocks(
+      parsed.system,
+      resolved.systemBreakpoints,
+      resolved.systemPlacement,
+      resolved.cacheType,
+    );
+    parsed.system = result.blocks;
+    systemUsed = result.used;
+  }
+
+  if (parsed.messages && Array.isArray(parsed.messages)) {
+    let messageUsed = 0;
+    const messageCount = parsed.messages.length;
+
+    const eligibleIndices: number[] = [];
+    for (let i = 0; i < messageCount; i++) {
+      if (shouldCacheAtIndex(i, messageCount, resolved.messageBreakpoints, resolved.messagePlacement)) {
+        eligibleIndices.push(i);
+      }
+    }
+
+    parsed.messages = parsed.messages.map((msg, msgIndex) => {
+      if (messageUsed >= resolved.messageBreakpoints) return msg;
+      if (!eligibleIndices.includes(msgIndex)) return msg;
+
+      if (Array.isArray(msg.content)) {
+        const blocks = msg.content as MessageBlock[];
+        const lastIdx = blocks.length - 1;
+        const content = blocks.map((block, blockIndex) => {
+          if (block.cache_control) return block;
+          if (blockIndex === lastIdx && messageUsed < resolved.messageBreakpoints) {
+            messageUsed++;
+            return { ...block, cache_control: { type: resolved.cacheType } };
+          }
+          return block;
+        });
+        return { ...msg, content };
+      }
+
+      if (typeof msg.content === 'string' && messageUsed < resolved.messageBreakpoints) {
+        messageUsed++;
+        return {
+          ...msg,
+          content: [
+            {
+              type: 'text',
+              text: msg.content,
+              cache_control: { type: resolved.cacheType },
+            },
+          ],
+        };
+      }
+
+      return msg;
+    });
+  }
+
+  return parsed;
+}

package/src/fetch.ts

@@ -0,0 +1,288 @@
+import type { WalletContext } from './auth.ts';
+import type { PaymentCallbacks, PaymentOptions, CacheOptions, BalanceUpdate, AnthropicCacheConfig } from './types.ts';
+import { buildWalletHeaders } from './auth.ts';
+import { pickPaymentRequirement, handlePayment } from './payment.ts';
+import { addAnthropicCacheControl } from './cache.ts';
+
+const DEFAULT_RPC_URL = 'https://api.mainnet-beta.solana.com';
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_MAX_PAYMENT_ATTEMPTS = 20;
+
+interface PaymentQueueEntry {
+  promise: Promise<void>;
+  resolve: () => void;
+}
+
+const paymentQueues = new Map<string, PaymentQueueEntry>();
+const globalPaymentAttempts = new Map<string, number>();
+
+async function acquirePaymentLock(walletAddress: string): Promise<() => void> {
+  const existing = paymentQueues.get(walletAddress);
+
+  let resolveFunc: () => void = () => {};
+  const newPromise = new Promise<void>((resolve) => {
+    resolveFunc = resolve;
+  });
+
+  const entry: PaymentQueueEntry = { promise: newPromise, resolve: resolveFunc };
+  paymentQueues.set(walletAddress, entry);
+
+  if (existing) {
+    await existing.promise;
+  }
+
+  return () => {
+    if (paymentQueues.get(walletAddress) === entry) {
+      paymentQueues.delete(walletAddress);
+    }
+    resolveFunc();
+  };
+}
+
+function tryParseSetuComment(
+  line: string,
+  onBalanceUpdate: (update: BalanceUpdate) => void,
+) {
+  const trimmed = line.replace(/\r$/, '');
+  if (!trimmed.startsWith(': setu ')) return;
+  try {
+    const data = JSON.parse(trimmed.slice(7));
+    onBalanceUpdate({
+      costUsd: parseFloat(data.cost_usd ?? '0'),
+      balanceRemaining: parseFloat(data.balance_remaining ?? '0'),
+      inputTokens: data.input_tokens ? Number(data.input_tokens) : undefined,
+      outputTokens: data.output_tokens ? Number(data.output_tokens) : undefined,
+    });
+  } catch {}
+}
+
+function wrapResponseWithBalanceSniffing(
+  response: Response,
+  callbacks: PaymentCallbacks,
+): Response {
+  if (!callbacks.onBalanceUpdate) return response;
+
+  const balanceHeader = response.headers.get('x-balance-remaining');
+  const costHeader = response.headers.get('x-cost-usd');
+  if (balanceHeader && costHeader) {
+    callbacks.onBalanceUpdate({
+      costUsd: parseFloat(costHeader),
+      balanceRemaining: parseFloat(balanceHeader),
+    });
+    return response;
+  }
+
+  if (!response.body) return response;
+
+  const onBalanceUpdate = callbacks.onBalanceUpdate;
+  let partial = '';
+  const decoder = new TextDecoder();
+  const transform = new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      controller.enqueue(chunk);
+      partial += decoder.decode(chunk, { stream: true });
+      let nlIndex = partial.indexOf('\n');
+      while (nlIndex !== -1) {
+        const line = partial.slice(0, nlIndex);
+        partial = partial.slice(nlIndex + 1);
+        tryParseSetuComment(line, onBalanceUpdate);
+        nlIndex = partial.indexOf('\n');
+      }
+    },
+    flush() {
+      if (partial.trim()) {
+        tryParseSetuComment(partial, onBalanceUpdate);
+      }
+    },
+  });
+
+  return new Response(response.body.pipeThrough(transform), {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}
+
+async function getWalletUsdcBalance(
+  walletAddress: string,
+  rpcUrl: string,
+): Promise<number> {
+  const USDC_MINT_MAINNET = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+  const USDC_MINT_DEVNET = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU';
+
+  try {
+    const usdcMint = rpcUrl.includes('devnet') ? USDC_MINT_DEVNET : USDC_MINT_MAINNET;
+    const response = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'getTokenAccountsByOwner',
+        params: [walletAddress, { mint: usdcMint }, { encoding: 'jsonParsed' }],
+      }),
+    });
+    if (!response.ok) return 0;
+    const data = (await response.json()) as {
+      result?: {
+        value?: Array<{
+          account: {
+            data: { parsed: { info: { tokenAmount: { uiAmount: number } } } };
+          };
+        }>;
+      };
+    };
+    let total = 0;
+    for (const acct of data.result?.value ?? []) {
+      total += acct.account.data.parsed.info.tokenAmount.uiAmount ?? 0;
+    }
+    return total;
+  } catch {
+    return 0;
+  }
+}
+
+export interface CreateSetuFetchOptions {
+  wallet: WalletContext;
+  baseURL: string;
+  rpcURL?: string;
+  callbacks?: PaymentCallbacks;
+  cache?: CacheOptions;
+  payment?: PaymentOptions;
+}
+
+export function createSetuFetch(options: CreateSetuFetchOptions) {
+  const {
+    wallet,
+    baseURL,
+    rpcURL = DEFAULT_RPC_URL,
+    callbacks = {},
+    cache,
+    payment,
+  } = options;
+
+  const maxAttempts = payment?.maxRequestAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const maxPaymentAttempts = payment?.maxPaymentAttempts ?? DEFAULT_MAX_PAYMENT_ATTEMPTS;
+  const topupApprovalMode = payment?.topupApprovalMode ?? 'auto';
+  const autoPayThresholdUsd = payment?.autoPayThresholdUsd ?? 0;
+  const baseFetch = globalThis.fetch.bind(globalThis);
+
+  return async (
+    input: Parameters<typeof fetch>[0],
+    init?: Parameters<typeof fetch>[1],
+  ) => {
+    let attempt = 0;
+
+    while (attempt < maxAttempts) {
+      attempt++;
+      let body = init?.body;
+      if (body && typeof body === 'string') {
+        try {
+          const parsed = JSON.parse(body);
+          if (cache?.promptCacheKey) parsed.prompt_cache_key = cache.promptCacheKey;
+          if (cache?.promptCacheRetention) parsed.prompt_cache_retention = cache.promptCacheRetention;
+          const cacheConfig = cache?.anthropicCaching;
+          if (cacheConfig !== false) {
+            const anthropicConfig = typeof cacheConfig === 'object' ? cacheConfig : undefined;
+            addAnthropicCacheControl(parsed, anthropicConfig);
+          }
+          body = JSON.stringify(parsed);
+        } catch {}
+      }
+
+      const headers = new Headers(init?.headers);
+      const walletHeaders = buildWalletHeaders(wallet);
+      headers.set('x-wallet-address', walletHeaders['x-wallet-address']!);
+      headers.set('x-wallet-nonce', walletHeaders['x-wallet-nonce']!);
+      headers.set('x-wallet-signature', walletHeaders['x-wallet-signature']!);
+
+      const response = await baseFetch(input, { ...init, body, headers });
+
+      if (response.status !== 402) {
+        return wrapResponseWithBalanceSniffing(response, callbacks);
+      }
+
+      const payload = await response.json().catch(() => ({}));
+      const requirement = pickPaymentRequirement(payload);
+      if (!requirement) {
+        callbacks.onPaymentError?.('Unsupported payment requirement');
+        throw new Error('Setu: unsupported payment requirement');
+      }
+      if (attempt >= maxAttempts) {
+        callbacks.onPaymentError?.('Payment failed after multiple attempts');
+        throw new Error('Setu: payment failed after multiple attempts');
+      }
+
+      const currentAttempts = globalPaymentAttempts.get(wallet.walletAddress) ?? 0;
+      const remainingPayments = maxPaymentAttempts - currentAttempts;
+      if (remainingPayments <= 0) {
+        callbacks.onPaymentError?.('Maximum payment attempts exceeded');
+        throw new Error('Setu: payment failed after maximum payment attempts.');
+      }
+
+      const releaseLock = await acquirePaymentLock(wallet.walletAddress);
+
+      try {
+        const amountUsd = parseInt(requirement.maxAmountRequired, 10) / 1_000_000;
+        let walletUsdcBalance = 0;
+        if (autoPayThresholdUsd > 0) {
+          walletUsdcBalance = await getWalletUsdcBalance(wallet.walletAddress, rpcURL);
+        }
+
+        const canAutoPay = autoPayThresholdUsd > 0 && walletUsdcBalance >= autoPayThresholdUsd;
+
+        const requestApproval = async () => {
+          if (!callbacks.onPaymentApproval) return;
+          const approval = await callbacks.onPaymentApproval({
+            amountUsd,
+            currentBalance: walletUsdcBalance,
+          });
+          if (approval === 'cancel') {
+            callbacks.onPaymentError?.('Payment cancelled by user');
+            throw new Error('Setu: payment cancelled by user');
+          }
+          if (approval === 'fiat') {
+            const err = new Error('Setu: fiat payment selected') as Error & { code: string };
+            err.code = 'SETU_FIAT_SELECTED';
+            throw err;
+          }
+        };
+
+        if (!canAutoPay && topupApprovalMode === 'approval') {
+          await requestApproval();
+        }
+
+        callbacks.onPaymentRequired?.(amountUsd, walletUsdcBalance);
+
+        const doPayment = async () => {
+          const outcome = await handlePayment({
+            requirement,
+            wallet,
+            rpcURL,
+            baseURL,
+            baseFetch,
+            maxAttempts: remainingPayments,
+            callbacks,
+          });
+          const newTotal = currentAttempts + outcome.attemptsUsed;
+          globalPaymentAttempts.set(wallet.walletAddress, newTotal);
+        };
+
+        if (canAutoPay) {
+          try {
+            await doPayment();
+          } catch {
+            await requestApproval();
+            await doPayment();
+          }
+        } else {
+          await doPayment();
+        }
+      } finally {
+        releaseLock();
+      }
+    }
+
+    throw new Error('Setu: max attempts exceeded');
+  };
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+export { createSetu } from './setu.ts';
+export type { SetuInstance, SetuProvider } from './setu.ts';
+
+export type {
+  SetuConfig,
+  SetuAuth,
+  ProviderId,
+  ProviderApiFormat,
+  ProviderConfig,
+  PaymentCallbacks,
+  PaymentOptions,
+  CacheOptions,
+  BalanceUpdate,
+  BalanceResponse,
+  WalletUsdcBalance,
+  ExactPaymentRequirement,
+  PaymentPayload,
+  FetchFunction,
+  AnthropicCacheStrategy,
+  AnthropicCachePlacement,
+  AnthropicCacheConfig,
+} from './types.ts';
+
+export { ProviderRegistry } from './providers/registry.ts';
+export { createModel } from './providers/factory.ts';
+
+export { createSetuFetch } from './fetch.ts';
+export type { CreateSetuFetchOptions } from './fetch.ts';
+
+export { fetchBalance, fetchWalletUsdcBalance } from './balance.ts';
+export { getPublicKeyFromPrivate } from './auth.ts';
+export { addAnthropicCacheControl } from './cache.ts';

package/src/payment.ts

@@ -0,0 +1,171 @@
+import { Buffer } from 'node:buffer';
+import bs58 from 'bs58';
+import { createPaymentHeader } from 'x402/client';
+import { svm } from 'x402/shared';
+import type { PaymentRequirements } from 'x402/types';
+import type { WalletContext } from './auth.ts';
+import type {
+  ExactPaymentRequirement,
+  PaymentPayload,
+  PaymentCallbacks,
+} from './types.ts';
+import { buildWalletHeaders } from './auth.ts';
+
+function simplifyPaymentError(errMsg: string): string {
+  const lower = errMsg.toLowerCase();
+  if (lower.includes('insufficient') || lower.includes('not enough') || lower.includes('balance'))
+    return 'Insufficient USDC balance';
+  if (lower.includes('simulation') || lower.includes('compute unit'))
+    return 'Transaction simulation failed';
+  if (lower.includes('blockhash') || lower.includes('expired'))
+    return 'Transaction expired, please retry';
+  if (lower.includes('timeout') || lower.includes('timed out'))
+    return 'Transaction timed out';
+  if (lower.includes('rejected') || lower.includes('cancelled'))
+    return 'Transaction rejected';
+  if (lower.includes('network') || lower.includes('connection'))
+    return 'Network error';
+  const short = (errMsg.split('.')[0] ?? errMsg).slice(0, 80);
+  return short.length < errMsg.length ? `${short}...` : errMsg;
+}
+
+export function pickPaymentRequirement(
+  payload: unknown,
+): ExactPaymentRequirement | null {
+  const acceptsValue =
+    typeof payload === 'object' && payload !== null
+      ? (payload as { accepts?: unknown }).accepts
+      : undefined;
+  const accepts = Array.isArray(acceptsValue)
+    ? (acceptsValue as ExactPaymentRequirement[])
+    : [];
+  return accepts.find((opt) => opt && opt.scheme === 'exact') ?? null;
+}
+
+export async function createPaymentPayload(
+  requirement: ExactPaymentRequirement,
+  wallet: WalletContext,
+  rpcURL: string,
+): Promise<PaymentPayload> {
+  const privateKeyBase58 = bs58.encode(wallet.keypair.secretKey);
+  const signer = await svm.createSignerFromBase58(privateKeyBase58);
+  const header = await createPaymentHeader(
+    signer,
+    1,
+    requirement as PaymentRequirements,
+    { svmConfig: { rpcUrl: rpcURL } },
+  );
+  const decoded = JSON.parse(
+    Buffer.from(header, 'base64').toString('utf-8'),
+  ) as { payload: { transaction: string } };
+
+  return {
+    x402Version: 1,
+    scheme: 'exact',
+    network: requirement.network,
+    payload: { transaction: decoded.payload.transaction },
+  };
+}
+
+interface PaymentResponse {
+  amount_usd?: number | string;
+  new_balance?: number | string;
+  amount?: number;
+  balance?: number;
+  transaction?: string;
+}
+
+export async function processSinglePayment(args: {
+  requirement: ExactPaymentRequirement;
+  wallet: WalletContext;
+  rpcURL: string;
+  baseURL: string;
+  baseFetch: typeof fetch;
+  callbacks: PaymentCallbacks;
+}): Promise<{ attempts: number; balance?: number | string }> {
+  args.callbacks.onPaymentSigning?.();
+
+  let paymentPayload: PaymentPayload;
+  try {
+    paymentPayload = await createPaymentPayload(
+      args.requirement,
+      args.wallet,
+      args.rpcURL,
+    );
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    const userMsg = `Payment failed: ${simplifyPaymentError(errMsg)}`;
+    args.callbacks.onPaymentError?.(userMsg);
+    throw new Error(`Setu: ${userMsg}`);
+  }
+
+  const walletHeaders = buildWalletHeaders(args.wallet);
+  const response = await args.baseFetch(`${args.baseURL}/v1/topup`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...walletHeaders },
+    body: JSON.stringify({
+      paymentPayload,
+      paymentRequirement: args.requirement,
+    }),
+  });
+
+  const rawBody = await response.text().catch(() => '');
+  if (!response.ok) {
+    if (response.status === 400 && rawBody.toLowerCase().includes('already processed')) {
+      return { attempts: 1 };
+    }
+    args.callbacks.onPaymentError?.(`Topup failed: ${response.status}`);
+    throw new Error(`Setu topup failed (${response.status}): ${rawBody}`);
+  }
+
+  let parsed: PaymentResponse | undefined;
+  try {
+    parsed = rawBody ? (JSON.parse(rawBody) as PaymentResponse) : undefined;
+  } catch {
+    parsed = undefined;
+  }
+
+  if (parsed) {
+    const amountUsd =
+      typeof parsed.amount_usd === 'string'
+        ? parseFloat(parsed.amount_usd)
+        : (parsed.amount_usd ?? parsed.amount ?? 0);
+    const newBalance =
+      typeof parsed.new_balance === 'string'
+        ? parseFloat(parsed.new_balance)
+        : (parsed.new_balance ?? parsed.balance ?? 0);
+    args.callbacks.onPaymentComplete?.({
+      amountUsd,
+      newBalance,
+      transactionId: parsed.transaction,
+    });
+    return { attempts: 1, balance: newBalance };
+  }
+  return { attempts: 1 };
+}
+
+export async function handlePayment(args: {
+  requirement: ExactPaymentRequirement;
+  wallet: WalletContext;
+  rpcURL: string;
+  baseURL: string;
+  baseFetch: typeof fetch;
+  maxAttempts: number;
+  callbacks: PaymentCallbacks;
+}): Promise<{ attemptsUsed: number }> {
+  let attempts = 0;
+  while (attempts < args.maxAttempts) {
+    const result = await processSinglePayment(args);
+    attempts += result.attempts;
+    const balanceValue =
+      typeof result.balance === 'number'
+        ? result.balance
+        : result.balance != null
+          ? Number(result.balance)
+          : undefined;
+    if (balanceValue == null || Number.isNaN(balanceValue) || balanceValue >= 0) {
+      return { attemptsUsed: attempts };
+    }
+  }
+  throw new Error(`Setu: payment failed after ${attempts} additional top-ups.`);
+}

package/src/providers/factory.ts

@@ -0,0 +1,55 @@
+import { createOpenAI } from '@ai-sdk/openai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import type { ProviderApiFormat, ProviderId, FetchFunction } from '../types.ts';
+
+export function createModel(
+  modelId: string,
+  apiFormat: ProviderApiFormat,
+  providerId: ProviderId,
+  baseURL: string,
+  customFetch: FetchFunction,
+) {
+  const fetchFn = customFetch as unknown as typeof globalThis.fetch;
+
+  switch (apiFormat) {
+    case 'anthropic-messages': {
+      const provider = createAnthropic({
+        baseURL,
+        apiKey: 'setu-wallet-auth',
+        fetch: fetchFn,
+      });
+      return provider(modelId);
+    }
+
+    case 'google-native': {
+      const provider = createGoogleGenerativeAI({
+        baseURL,
+        apiKey: 'setu-wallet-auth',
+        fetch: fetchFn,
+      });
+      return provider(modelId);
+    }
+
+    case 'openai-chat': {
+      const provider = createOpenAICompatible({
+        name: `setu-${providerId}`,
+        baseURL,
+        headers: { Authorization: 'Bearer setu-wallet-auth' },
+        fetch: fetchFn,
+      });
+      return provider(modelId);
+    }
+
+    case 'openai-responses':
+    default: {
+      const provider = createOpenAI({
+        baseURL,
+        apiKey: 'setu-wallet-auth',
+        fetch: fetchFn,
+      });
+      return provider.responses(modelId);
+    }
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,2 @@
+export { ProviderRegistry } from './registry.ts';
+export { createModel } from './factory.ts';

package/src/providers/registry.ts

@@ -0,0 +1,100 @@
+import type { ProviderId, ProviderConfig, ProviderApiFormat } from '../types.ts';
+
+const BUILTIN_PROVIDERS: ProviderConfig[] = [
+  {
+    id: 'openai',
+    apiFormat: 'openai-responses',
+    modelPrefix: 'gpt-',
+  },
+  {
+    id: 'openai',
+    apiFormat: 'openai-responses',
+    modelPrefix: 'o1',
+  },
+  {
+    id: 'openai',
+    apiFormat: 'openai-responses',
+    modelPrefix: 'o3',
+  },
+  {
+    id: 'openai',
+    apiFormat: 'openai-responses',
+    modelPrefix: 'o4',
+  },
+  {
+    id: 'openai',
+    apiFormat: 'openai-responses',
+    modelPrefix: 'codex-',
+  },
+  {
+    id: 'anthropic',
+    apiFormat: 'anthropic-messages',
+    modelPrefix: 'claude-',
+  },
+  {
+    id: 'google',
+    apiFormat: 'google-native',
+    modelPrefix: 'gemini-',
+  },
+  {
+    id: 'moonshot',
+    apiFormat: 'openai-chat',
+    modelPrefix: 'kimi-',
+  },
+  {
+    id: 'minimax',
+    apiFormat: 'anthropic-messages',
+    modelPrefix: 'MiniMax-',
+  },
+  {
+    id: 'zai',
+    apiFormat: 'openai-chat',
+    modelPrefix: 'z1-',
+  },
+];
+
+export class ProviderRegistry {
+  private configs: ProviderConfig[];
+  private modelMap: Record<string, ProviderId>;
+
+  constructor(
+    customProviders?: ProviderConfig[],
+    modelMap?: Record<string, ProviderId>,
+  ) {
+    this.configs = [...BUILTIN_PROVIDERS, ...(customProviders ?? [])];
+    this.modelMap = modelMap ?? {};
+  }
+
+  resolve(modelId: string): { providerId: ProviderId; apiFormat: ProviderApiFormat } | null {
+    if (this.modelMap[modelId]) {
+      const providerId = this.modelMap[modelId];
+      const config = this.configs.find((c) => c.id === providerId);
+      return {
+        providerId,
+        apiFormat: config?.apiFormat ?? 'openai-chat',
+      };
+    }
+
+    for (const config of this.configs) {
+      if (config.models?.includes(modelId)) {
+        return { providerId: config.id, apiFormat: config.apiFormat };
+      }
+    }
+
+    for (const config of this.configs) {
+      if (config.modelPrefix && modelId.startsWith(config.modelPrefix)) {
+        return { providerId: config.id, apiFormat: config.apiFormat };
+      }
+    }
+
+    return null;
+  }
+
+  register(config: ProviderConfig): void {
+    this.configs.push(config);
+  }
+
+  mapModel(modelId: string, providerId: ProviderId): void {
+    this.modelMap[modelId] = providerId;
+  }
+}

package/src/setu.ts

@@ -0,0 +1,87 @@
+import type { SetuConfig, ProviderId, ProviderApiFormat, FetchFunction, BalanceResponse, WalletUsdcBalance } from './types.ts';
+import { createWalletContext, getPublicKeyFromPrivate } from './auth.ts';
+import { createSetuFetch } from './fetch.ts';
+import { ProviderRegistry } from './providers/registry.ts';
+import { createModel } from './providers/factory.ts';
+import { fetchBalance, fetchWalletUsdcBalance } from './balance.ts';
+
+const DEFAULT_BASE_URL = 'https://api.setu.ottocode.io';
+
+function trimTrailingSlash(url: string) {
+  return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+
+export interface SetuProvider {
+  model(modelId: string): ReturnType<typeof createModel>;
+}
+
+export interface SetuInstance {
+  model(modelId: string): ReturnType<typeof createModel>;
+  provider(providerId: ProviderId, apiFormat?: ProviderApiFormat): SetuProvider;
+  fetch(): FetchFunction;
+  balance(): Promise<BalanceResponse | null>;
+  walletBalance(network?: 'mainnet' | 'devnet'): Promise<WalletUsdcBalance | null>;
+  walletAddress: string | null;
+  registry: ProviderRegistry;
+}
+
+export function createSetu(config: SetuConfig): SetuInstance {
+  const baseURL = trimTrailingSlash(config.baseURL ?? DEFAULT_BASE_URL);
+  const wallet = createWalletContext(config.auth);
+  const registry = new ProviderRegistry(config.providers, config.modelMap);
+
+  const setuFetch = createSetuFetch({
+    wallet,
+    baseURL,
+    rpcURL: config.rpcURL,
+    callbacks: config.callbacks,
+    cache: config.cache,
+    payment: config.payment,
+  });
+
+  const modelBaseURL = `${baseURL}/v1`;
+
+  return {
+    model(modelId: string) {
+      const resolved = registry.resolve(modelId);
+      if (!resolved) {
+        throw new Error(
+          `Setu: unknown model "${modelId}". Register it via providers or modelMap config.`,
+        );
+      }
+      return createModel(
+        modelId,
+        resolved.apiFormat,
+        resolved.providerId,
+        modelBaseURL,
+        setuFetch,
+      );
+    },
+
+    provider(providerId: ProviderId, apiFormat?: ProviderApiFormat): SetuProvider {
+      return {
+        model(modelId: string) {
+          const resolved = registry.resolve(modelId);
+          const format = apiFormat ?? resolved?.apiFormat ?? 'openai-chat';
+          return createModel(modelId, format, providerId, modelBaseURL, setuFetch);
+        },
+      };
+    },
+
+    fetch(): FetchFunction {
+      return setuFetch;
+    },
+
+    async balance() {
+      return fetchBalance(config.auth, baseURL);
+    },
+
+    async walletBalance(network?: 'mainnet' | 'devnet') {
+      return fetchWalletUsdcBalance(config.auth, network);
+    },
+
+    walletAddress: getPublicKeyFromPrivate(config.auth.privateKey),
+
+    registry,
+  };
+}

package/src/types.ts

@@ -0,0 +1,119 @@
+export type ProviderId =
+  | 'openai'
+  | 'anthropic'
+  | 'google'
+  | 'moonshot'
+  | 'zai'
+  | 'minimax'
+  | (string & {});
+
+export type ProviderApiFormat = 'openai-responses' | 'anthropic-messages' | 'openai-chat' | 'google-native';
+
+export type FetchFunction = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export interface ProviderConfig {
+  id: ProviderId;
+  apiFormat: ProviderApiFormat;
+  models?: string[];
+  modelPrefix?: string;
+}
+
+export interface SetuAuth {
+  privateKey: string;
+}
+
+export interface BalanceUpdate {
+  costUsd: number;
+  balanceRemaining: number;
+  inputTokens?: number;
+  outputTokens?: number;
+}
+
+export interface PaymentCallbacks {
+  onPaymentRequired?: (amountUsd: number, currentBalance?: number) => void;
+  onPaymentSigning?: () => void;
+  onPaymentComplete?: (data: {
+    amountUsd: number;
+    newBalance: number;
+    transactionId?: string;
+  }) => void;
+  onPaymentError?: (error: string) => void;
+  onPaymentApproval?: (info: {
+    amountUsd: number;
+    currentBalance: number;
+  }) => Promise<'crypto' | 'fiat' | 'cancel'>;
+  onBalanceUpdate?: (update: BalanceUpdate) => void;
+}
+
+export type AnthropicCacheStrategy = 'auto' | 'manual' | 'custom' | false;
+
+export type AnthropicCachePlacement = 'first' | 'last' | 'all';
+
+export interface AnthropicCacheConfig {
+  strategy?: AnthropicCacheStrategy;
+  systemBreakpoints?: number;
+  messageBreakpoints?: number;
+  systemPlacement?: AnthropicCachePlacement;
+  messagePlacement?: AnthropicCachePlacement;
+  cacheType?: 'ephemeral';
+  transform?: (body: Record<string, unknown>) => Record<string, unknown>;
+}
+
+export interface CacheOptions {
+  promptCacheKey?: string;
+  promptCacheRetention?: 'in_memory' | '24h';
+  anthropicCaching?: boolean | AnthropicCacheConfig;
+}
+
+export interface PaymentOptions {
+  topupApprovalMode?: 'auto' | 'approval';
+  autoPayThresholdUsd?: number;
+  maxRequestAttempts?: number;
+  maxPaymentAttempts?: number;
+}
+
+export interface SetuConfig {
+  auth: SetuAuth;
+  baseURL?: string;
+  rpcURL?: string;
+  providers?: ProviderConfig[];
+  modelMap?: Record<string, ProviderId>;
+  callbacks?: PaymentCallbacks;
+  cache?: CacheOptions;
+  payment?: PaymentOptions;
+}
+
+export interface ExactPaymentRequirement {
+  scheme: 'exact';
+  network: string;
+  maxAmountRequired: string;
+  asset: string;
+  payTo: string;
+  description?: string;
+  resource?: string;
+  extra?: Record<string, unknown>;
+  maxTimeoutSeconds?: number;
+}
+
+export interface PaymentPayload {
+  x402Version: 1;
+  scheme: 'exact';
+  network: string;
+  payload: { transaction: string };
+}
+
+export interface BalanceResponse {
+  walletAddress: string;
+  balance: number;
+  totalSpent: number;
+  totalTopups: number;
+  requestCount: number;
+  createdAt?: string;
+  lastRequest?: string;
+}
+
+export interface WalletUsdcBalance {
+  walletAddress: string;
+  usdcBalance: number;
+  network: 'mainnet' | 'devnet';
+}