@agents-eco/sdk

Official TypeScript/JavaScript SDK for the agents.eco API.

Installation

npm install @agents-eco/sdk

Quick Start

import { AgentsEco } from "@agents-eco/sdk";

const client = new AgentsEco({ apiKey: "ak_your_api_key" });

// Check balance
const { availableBalanceUsdc } = await client.getBalance();
console.log(`Balance: $${(Number(availableBalanceUsdc) / 1e6).toFixed(2)} USDC`);

// Create an agent
const agent = await client.createAgent({
  name: "Research Bot",
  systemPrompt: "You are a helpful research assistant.",
  memoryEnabled: true,
});
console.log(`Created agent: ${agent.id}`);

// Chat with the agent
const response = await client.chat(agent.id, "What are the latest trends in AI?");
console.log(response.response);

Authentication

There are two ways to authenticate:

API Key (recommended for server-side)

const client = new AgentsEco({ apiKey: "ak_your_api_key" });

Session Token (for browser/wallet-based auth)

// 1. Get a challenge
const challenge = await AgentsEco.getChallenge(walletAddress, "login");

// 2. Sign the message with the user's wallet
const signature = await wallet.signMessage(challenge.message);

// 3. Login
const { sessionToken } = await AgentsEco.walletLogin({
  wallet: walletAddress,
  nonce: challenge.nonce,
  signature,
});

// 4. Create client with session token
const client = new AgentsEco({ apiKey: sessionToken });

API Reference

Constructor

new AgentsEco({
  apiKey: string;        // Required — API key or session token
  baseUrl?: string;      // Default: "https://agents.eco"
  timeout?: number;      // Default: 30000 (ms)
  headers?: Record<string, string>;  // Extra headers
  fetch?: typeof fetch;  // Custom fetch (for Node 16 or testing)
});

Auth (Static Methods)

| Method | Description | |--------|-------------| | AgentsEco.getChallenge(wallet, purpose) | Get a nonce challenge for wallet auth | | AgentsEco.register(data) | Register a new account | | AgentsEco.walletLogin(data) | Login with wallet signature | | AgentsEco.getSkills() | Get platform skills docs (public) |

Auth (Authenticated)

| Method | Description | |--------|-------------| | client.getProfile() | Get current user profile | | client.regenerateApiKey() | Regenerate API key (invalidates current) |

Wallet

| Method | Description | |--------|-------------| | client.getBalance() | Get USDC balance | | client.getDepositAddress() | Get vault address for deposits | | client.verifyDeposit({ txHash }) | Verify and credit an on-chain deposit |

Agents

| Method | Description | |--------|-------------| | client.getAgentConfig() | Get creation pricing | | client.listAgents() | List all your agents | | client.createAgent(data) | Create a new agent | | client.getAgent(id) | Get agent details + runs | | client.chat(id, message) | Chat with an agent | | client.updateAgent(id, data) | Update agent settings | | client.deleteAgent(id) | Delete an agent |

Inference

| Method | Description | |--------|-------------| | client.infer(data, idempotencyKey?) | Run model inference | | client.getInferenceStatus(requestId) | Get inference result |

Billing

| Method | Description | |--------|-------------| | client.getLedger({ limit?, offset?, type? }) | Get transaction history | | client.getReceipts({ limit?, offset? }) | Get billing receipts |

Models

| Method | Description | |--------|-------------| | client.listModels({ limit?, offset?, task? }) | List available models | | client.registerModel(data) | Register a new model |

Providers

| Method | Description | |--------|-------------| | client.getProviders() | Get provider status + models |

Error Handling

import { AgentsEco, AgentsEcoError } from "@agents-eco/sdk";

try {
  await client.chat("invalid-id", "hello");
} catch (err) {
  if (err instanceof AgentsEcoError) {
    console.error(`API Error ${err.status}: ${err.message}`);
    // err.body contains the full error response
  }
}

Examples

Deposit and Create Agent

const client = new AgentsEco({ apiKey: "ak_..." });

// Get deposit address
const { vaultAddress, chainName } = await client.getDepositAddress();
console.log(`Send USDC to ${vaultAddress} on ${chainName}`);

// After sending USDC on-chain, verify the deposit
const deposit = await client.verifyDeposit({ txHash: "0x..." });
console.log(`Credited: ${(Number(deposit.amountUsdc) / 1e6).toFixed(2)} USDC`);

// Create agent
const agent = await client.createAgent({
  name: "My Bot",
  systemPrompt: "You are a helpful assistant.",
  memoryEnabled: true,
  reasoningEnabled: true,
});

// Chat
const res = await client.chat(agent.id, "Hello!");
console.log(res.response);

Run Raw Inference

const result = await client.infer({
  modelId: "qwen-3b",
  input: { messages: [{ role: "user", content: "Explain quantum computing" }] },
});
console.log(result.output);
console.log(`Cost: ${(Number(result.costCredits) / 1e6).toFixed(6)} USDC`);

List Transactions

const ledger = await client.getLedger({ limit: 10 });
for (const entry of ledger.entries) {
  const usd = (Number(entry.amountCredits) / 1e6).toFixed(4);
  console.log(`${entry.type}: $${usd} — ${entry.createdAt}`);
}

License

MIT