AiMo Network SDK

The official TypeScript SDK for interacting with AiMo Network. Provides wallet-based authentication, automatic payment handling, and OpenAI-compatible chat completions.

Installation

Install the packages you need:

# Core client (required)
npm install @aimo.network/client

# For Solana wallet support
npm install @aimo.network/svm

# For Ethereum/EVM wallet support  
npm install @aimo.network/evm

# For Vercel AI SDK integration (optional)
npm install @aimo.network/provider ai

Quick Start

Solana (SVM) Example

import { AimoClient } from "@aimo.network/client";
import { SvmClientSigner, SOLANA_MAINNET_CHAIN_ID } from "@aimo.network/svm";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import bs58 from "bs58";

// Create a Solana keypair signer from your private key
const privateKeyBytes = bs58.decode("your-base58-private-key");
const keypairSigner = await createKeyPairSignerFromBytes(privateKeyBytes);

// Create the client signer
const signer = new SvmClientSigner({
  signer: keypairSigner,
  chainId: SOLANA_MAINNET_CHAIN_ID,
});

// Create the AiMo client
const client = new AimoClient({
  signer,
  baseUrl: "https://beta.aimo.network",
});

// Query your session balance
const balance = await client.sessionBalance();
console.log(`Balance: ${balance.balance_usd} USD`);
console.log(`Account: ${balance.caip_account_id}`);

// Make a chat completion request
const response = await client.chatCompletions({
  model: "openai/gpt-5",
  messages: [{ role: "user", content: "Hello, what is AiMo Network?" }],
});

if (response.ok) {
  const data = await response.json();
  console.log(data.choices[0].message.content);
}

Ethereum/EVM Example

import { AimoClient } from "@aimo.network/client";
import { EvmClientSigner, EVM_MAINNET_CHAIN_ID } from "@aimo.network/evm";
import { privateKeyToAccount } from "viem/accounts";

// Create an EVM account from your private key
const account = privateKeyToAccount("0x...");

// Create the client signer
const signer = new EvmClientSigner({
  signer: account,
  chainId: EVM_MAINNET_CHAIN_ID,
});

// Create the AiMo client
const client = new AimoClient({
  signer,
  baseUrl: "https://beta.aimo.network",
});

// Use the client (same API as SVM example)
const balance = await client.sessionBalance();
console.log(`Balance: ${balance.balance_usd} USD`);

Core Features

Authentication

The SDK uses SIWx (Sign-In-With-X) for wallet-based authentication. Every request is automatically signed with your wallet, providing permissionless access without API keys.

// Authentication happens automatically when you create a client with a signer
const client = new AimoClient({
  signer,  // SvmClientSigner or EvmClientSigner
  baseUrl: "https://beta.aimo.network",
});

// All requests are automatically authenticated
const balance = await client.sessionBalance();

Payment Handling

The SDK integrates with X402 for automatic micropayment handling. When you make API requests that require payment, the SDK handles it transparently.

// Payments are handled automatically via:
// 1. Session balance (if you've pre-funded your wallet identity)
// 2. X402 per-request payments (if supported)

const response = await client.chatCompletions({
  model: "openai/gpt-5",
  messages: [{ role: "user", content: "Hello!" }],
});

Streaming Responses

The SDK supports OpenAI-compatible streaming:

const response = await client.chatCompletions({
  model: "openai/gpt-5",
  messages: [{ role: "user", content: "Tell me a story" }],
  stream: true,
});

// Handle Server-Sent Events (SSE)
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.trim());
  
  for (const line of lines) {
    if (line.startsWith('data: ') && line.slice(6) !== '[DONE]') {
      const data = JSON.parse(line.slice(6));
      const content = data.choices[0]?.delta?.content;
      if (content) {
        process.stdout.write(content);
      }
    }
  }
}

Vercel AI SDK Integration

The @aimo.network/provider package provides seamless integration with Vercel's AI SDK:

import { aimoNetwork } from "@aimo.network/provider";
import { SvmClientSigner, SOLANA_MAINNET_CHAIN_ID } from "@aimo.network/svm";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { generateText, streamText } from "ai";
import bs58 from "bs58";

// Create your signer (SVM or EVM)
const privateKeyBytes = bs58.decode("your-base58-private-key");
const keypairSigner = await createKeyPairSignerFromBytes(privateKeyBytes);
const signer = new SvmClientSigner({
  signer: keypairSigner,
  chainId: SOLANA_MAINNET_CHAIN_ID,
});

// Create the AiMo Network provider
const aimo = aimoNetwork({
  signer,
  baseURL: "https://beta.aimo.network",
});

// Use with AI SDK's generateText
const result = await generateText({
  model: aimo.chat("openai/gpt-5"),
  prompt: "What is AiMo Network?",
});

console.log(result.text);

// Stream responses
const stream = await streamText({
  model: aimo.chat("openai/gpt-5"),
  prompt: "Tell me a story",
});

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

Chain Support

Solana (SVM)

import { SvmClientSigner, SOLANA_MAINNET_CHAIN_ID } from "@aimo.network/svm";

// Chain ID: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
const signer = new SvmClientSigner({
  signer: keypairSigner,
  chainId: SOLANA_MAINNET_CHAIN_ID,
});

// Custom RPC URL (optional)
const customSigner = new SvmClientSigner({
  signer: keypairSigner,
  chainId: SOLANA_MAINNET_CHAIN_ID,
  config: {
    rpcUrl: "https://your-rpc-provider.com",
  },
});

Ethereum/Base (EVM)

import { EvmClientSigner, EVM_MAINNET_CHAIN_ID } from "@aimo.network/evm";

// Chain ID: "eip155:8453" (Base mainnet)
const signer = new EvmClientSigner({
  signer: account,
  chainId: EVM_MAINNET_CHAIN_ID,
});

API Reference

AimoClient

Constructor

new AimoClient(options: AimoClientOptions)

Options:

signer: ClientSigner - The wallet signer for authentication and payments
baseUrl: string - API server URL (e.g., "https://beta.aimo.network")
apiBase?: string - API path prefix (default: "/api/v1")
siwxDomain?: string - Override SIWx signing domain (for local development)
fetchOverride?: typeof fetch - Custom fetch implementation

Methods

chatCompletions(body, init?): Promise<Response>

Makes an OpenAI-compatible chat completion request.

const response = await client.chatCompletions({
  model: "openai/gpt-5",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" }
  ],
  temperature: 0.7,
  max_tokens: 150,
  stream: false,
});

const data = await response.json();
console.log(data.choices[0].message.content);

sessionBalance(init?): Promise<SessionBalanceResponse>

Queries the session balance for the authenticated wallet.

const balance = await client.sessionBalance();
console.log(`CAIP Account: ${balance.caip_account_id}`);
console.log(`Balance (USD): ${balance.balance_usd}`);
console.log(`Balance (micro USDC): ${balance.balance_micro_usdc}`);

Response:

interface SessionBalanceResponse {
  caip_account_id: string;  // e.g., "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:..."
  balance_micro_usdc: number;  // Balance in micro USDC (1 USDC = 1,000,000)
  balance_usd: string;  // Human-readable USD balance
}

aimoNetwork (Vercel AI SDK Provider)

aimoNetwork(options: AimoNetworkOptions)

Creates an AI SDK-compatible provider.

Options:

signer: ClientSigner - Wallet signer
baseURL?: string - API URL (default: "https://beta.aimo.network")
fetch?: typeof fetch - Custom fetch
siwxDomain?: string - Override SIWx domain

Returns:

chat(modelId: string): LanguageModelV3 - Creates a chat model instance

const aimo = aimoNetwork({ signer });
const model = aimo.chat("openai/gpt-5");

// Use with any AI SDK function
const result = await generateText({ model, prompt: "Hello!" });

Advanced Usage

Local Development

When developing against a local server that validates against a production domain:

const client = new AimoClient({
  signer,
  baseUrl: "http://localhost:8000",
  siwxDomain: "beta.aimo.network",  // Override signing domain
});

Custom Fetch Interceptors

Add custom request/response handling:

const customFetch: typeof fetch = async (url, init) => {
  console.log(`Request: ${init?.method} ${url}`);
  const response = await fetch(url, init);
  console.log(`Response: ${response.status}`);
  return response;
};

const client = new AimoClient({
  signer,
  baseUrl: "https://beta.aimo.network",
  fetchOverride: customFetch,
});

Error Handling

try {
  const response = await client.chatCompletions({
    model: "openai/gpt-5",
    messages: [{ role: "user", content: "Hello!" }],
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(`API error: ${error.error}`);
  } else {
    const data = await response.json();
    console.log(data.choices[0].message.content);
  }
} catch (error) {
  console.error(`Request failed: ${error.message}`);
}

Examples

Multi-Turn Conversation

const messages = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "What is AiMo Network?" },
];

const response1 = await client.chatCompletions({
  model: "openai/gpt-5",
  messages,
});

const data1 = await response1.json();
messages.push(data1.choices[0].message);

// Continue conversation
messages.push({ role: "user", content: "How does it work?" });

const response2 = await client.chatCompletions({
  model: "openai/gpt-5",
  messages,
});

const data2 = await response2.json();
console.log(data2.choices[0].message.content);

Using Different Models

// GPT-4
const gpt4Response = await client.chatCompletions({
  model: "openai/gpt-5",
  messages: [{ role: "user", content: "Complex reasoning task" }],
});

// Claude
const claudeResponse = await client.chatCompletions({
  model: "anthropic/claude-opus-4.6",
  messages: [{ role: "user", content: "Creative writing task" }],
});

// Gemini
const geminiResponse = await client.chatCompletions({
  model: "google/gemini-2.0-flash-exp",
  messages: [{ role: "user", content: "Analysis task" }],
});

Best Practices

Security

// ✅ Load keys from environment variables
const privateKey = process.env.SOLANA_PRIVATE_KEY;

// ❌ Don't hardcode private keys
// const privateKey = "your-private-key-here";

Performance

// ✅ Reuse client instances
const client = new AimoClient({ signer, baseUrl });

// Use the same client for multiple requests
await client.chatCompletions({ ... });
await client.chatCompletions({ ... });

// ❌ Don't create new clients for each request
// await new AimoClient({ ... }).chatCompletions({ ... });

Error Recovery

async function chatWithRetry(client, body, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await client.chatCompletions(body);
      if (response.ok) return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }
}

Resources

GitHub: github.com/AIMOverse/aimo-sdk
NPM: @aimo.network/client
AI Agent Guide: /docs/overview/ai-agent-guide
API Reference: /api-reference

Package Versions

Check the latest versions on NPM:

Package	Description
@aimo.network/client	Core client library
@aimo.network/svm	Solana wallet support
@aimo.network/evm	Ethereum wallet support
@aimo.network/provider	Vercel AI SDK provider

SDK Reference