agentindex-sdk

The official SDK for Agent Index — the discovery layer for x402 AI agents.

Installation

npm install agentindex-sdk
# or
yarn add agentindex-sdk
# or
pnpm add agentindex-sdk

Quick Start

import { AgentIndex } from '@agentindex/sdk';

const client = new AgentIndex();

// Search for crypto price agents
const results = await client.search({ query: 'crypto price' });
console.log(results.results);

// Get trending agents
const trending = await client.trending();
console.log(trending.trending);

API Reference

Constructor

const client = new AgentIndex({
  baseUrl: 'https://api.theagentindex.app', // default
  timeout: 10000, // default, in milliseconds
});

Methods

search(options) — Search for agents

const results = await client.search({
  query: 'weather forecast',      // required
  category: 'weather',            // optional: crypto, defi, ai, weather, news, oracle
  maxPrice: 0.05,                 // optional: max USD per call
  limit: 20,                      // optional: default 10, max 50
});

// Returns: { count: number, results: Agent[] }

trending() — Get trending agents

const trending = await client.trending();
// Returns: { trending: Agent[], period: string }

health() — Check API status

const health = await client.health();
// Returns: { status: 'ok' | 'degraded' | 'down', timestamp: string }

recommend(options) — AI-powered recommendations

⚡ Premium endpoint — requires x402 payment ($0.005/call)

const recommendations = await client.recommend({
  useCase: 'I need real-time crypto prices for my trading bot',
  maxPrice: 0.02,
  limit: 5,
});

analytics(options) — Endpoint analytics

⚡ Premium endpoint — requires x402 payment ($0.01/call)

const analytics = await client.analytics({
  target: 'crypto',       // category or agent ID
  period: '7d',           // 24h, 7d, or 30d
});

// Returns: { totalCalls, uniqueCallers, revenue, topEndpoints, period }

Types

interface Agent {
  id: string;
  url: string;
  domain: string;
  description: string;
  priceUsd: number;
  category: string;
  health: 'healthy' | 'degraded' | 'down' | 'unknown';
  tier: 'A' | 'B' | 'C' | 'D';
  score: number;
  metadata?: Record<string, unknown>;
}

Framework Integrations

LangChain

import { AgentIndex, createLangChainTool } from '@agentindex/sdk';

// Create a tool for your LangChain agent
const tool = createLangChainTool();

// Use in your agent
const tools = [tool];

Quick Search Helper

import { searchAgents } from '@agentindex/sdk';

// One-liner search
const agents = await searchAgents('crypto prices', { category: 'defi' });

MCP Server

For Claude, Cursor, and other MCP-compatible clients:

npm install -g agent-index-mcp

Add to Claude Desktop config:

{
  "mcpServers": {
    "agent-index": {
      "command": "npx",
      "args": ["agent-index-mcp"]
    }
  }
}

Then ask Claude: "Search Agent Index for weather APIs"

Examples

Find the cheapest crypto price API

import { AgentIndex } from '@agentindex/sdk';

const client = new AgentIndex();

const results = await client.search({
  query: 'crypto price',
  category: 'crypto',
  maxPrice: 0.01,
  limit: 10,
});

// Sort by price
const cheapest = results.results.sort((a, b) => a.priceUsd - b.priceUsd);
console.log(`Cheapest: ${cheapest[0].url} at $${cheapest[0].priceUsd}/call`);

Filter by health status

const results = await client.search({ query: 'weather' });

const healthy = results.results.filter(a => a.health === 'healthy');
console.log(`${healthy.length} healthy agents found`);

Build an agent that finds and uses other agents

import { AgentIndex } from '@agentindex/sdk';

async function findBestAgent(capability: string) {
  const client = new AgentIndex();
  
  const results = await client.search({ query: capability, limit: 5 });
  
  // Pick the best one (highest score + healthy)
  const best = results.results
    .filter(a => a.health === 'healthy')
    .sort((a, b) => b.score - a.score)[0];
  
  if (!best) throw new Error(`No healthy agent found for: ${capability}`);
  
  return best;
}

// Your AI agent can now dynamically find tools
const weatherAgent = await findBestAgent('weather forecast');
console.log(`Using: ${weatherAgent.url}`);

Error Handling

import { AgentIndex, AgentIndexError } from '@agentindex/sdk';

const client = new AgentIndex();

try {
  const results = await client.search({ query: 'test' });
} catch (error) {
  if (error instanceof AgentIndexError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);
  }
}

Rate Limits

• Free tier: 100 requests/minute
• Premium endpoints: Unlimited (pay-per-call via x402)

For higher limits, contact us or use premium endpoints.

Support

• 📖 Documentation
• 💬 Discord
• 🐛 Issues
• 🐦 Twitter

License

MIT © 402 Agent Inc