@tokium-labs/sdk

TypeScript SDK for the Tokium API — built for AI agents.

Zero dependencies. Works in Node 18+, Deno, Bun, and edge runtimes.

What is Tokium?

Tokium is an API marketplace for AI agents. Instead of managing API keys, billing accounts, and rate limits for every third-party service your agent needs, Tokium gives you a single API key and a prepaid wallet. Your agent discovers APIs, calls them through Tokium's proxy, and pays per request — automatically.

Why agents use Tokium:

• One key, many APIs — access lead generation, email verification, data enrichment, web scraping, and more through a single X-PAY-KEY
• Pay-per-call — no subscriptions, no committed spend. Your agent only pays for what it uses
• Built-in cost control — check balance before expensive operations, track spend in real time
• Zero config — no need to sign up for individual API providers, manage credentials, or handle billing

Install

npm install @tokium-labs/sdk

Quick Start

Agent Mode (API Key)

For agents making proxy calls, checking balance, and tracking usage:

import { Tokium } from '@tokium-labs/sdk';

const tokium = new Tokium('sk-live-...');

// Browse available proxies
const proxies = await tokium.proxies.list({ category: 'search' });

// Make a proxy call
const result = await tokium.proxies.call(42, {
  method: 'POST',
  path: '/people/search',
  body: { query: 'CEO at Acme' },
});

console.log(result.data);  // proxy response
console.log(result.meta);  // { cost, responseTime, proxyCallId }

Owner Mode (JWT)

For account management, agent CRUD, payments, and crypto deposits:

import { Tokium } from '@tokium-labs/sdk';

// Login and get an authenticated instance
const tokium = await Tokium.login({ email: '[email protected]', password: '...' });

// Or register a new account
const tokium = await Tokium.register({ email: '[email protected]', password: '...' });

// Manage agents
const agents = await tokium.agents.list();
const created = await tokium.agents.create({ name: 'my-agent' });

// Fund an agent via Stripe
const checkout = await tokium.payments.createCheckout({ agentId: 1, amount: 10 });
console.log(checkout.checkoutUrl); // redirect user to pay

API Reference

Constructor

// Agent mode — API key auth (sends X-PAY-KEY header)
const tokium = new Tokium('sk-live-...', options?);

// Owner mode — bearer auth (sends Authorization: Bearer header)
const tokium = new Tokium('jwt-token', { authType: 'bearer' });

// No-auth mode — for public endpoints only
const tokium = new Tokium({ baseUrl: 'https://api.tokium.xyz' });

| Option | Type | Default | Description | |------------|-------------------------|--------------------------|----------------------| | baseUrl | string | https://api.tokium.xyz | API base URL | | timeout | number | 30000 | Request timeout (ms) | | authType | 'apikey' \| 'bearer' | 'apikey' | Authentication type |

Static Factory Methods

// Login — returns a bearer-authenticated Tokium instance
const tokium = await Tokium.login({ email, password, baseUrl? });

// Register — creates account and returns authenticated instance
const tokium = await Tokium.register({ email, password, baseUrl? });

Auth (Owner)

Requires bearer auth.

const profile = await tokium.auth.me();
// profile.ownerId, profile.email, profile.emailVerified

await tokium.auth.updateProfile({ firstName: 'Alice', lastName: 'Smith' });
await tokium.auth.changePassword({ currentPassword: '...', newPassword: '...' });
await tokium.auth.sendVerification();

Agents

// Agent mode (API key) — get the authenticated agent's info
const me = await tokium.agents.me();
// me.id, me.name, me.balance, me.dailySpendLimit, me.monthlySpendLimit

// Owner mode (bearer) — full CRUD
const agents = await tokium.agents.list();
const created = await tokium.agents.create({ name: 'new-agent', dailySpendLimit: 50 });
const updated = await tokium.agents.update(agentId, { name: 'renamed' });
const newKey = await tokium.agents.regenerateKey(agentId);
await tokium.agents.delete(agentId);

Proxies

const proxies = await tokium.proxies.list({ category: 'search' });
const proxy = await tokium.proxies.get(42);
const categories = await tokium.proxies.categories();
const docs = await tokium.proxies.skill(42);

const result = await tokium.proxies.call(42, {
  method: 'POST',
  path: '/people/search',
  body: { query: 'CEO at Acme' },
  headers: { 'X-Custom': 'value' },
  query: { limit: '10' },
});

Wallets

// Get balance (agentId is auto-resolved from your API key)
const balance = await tokium.wallets.balance();
// balance.agent  — { id, name, balance, createdAt }
// balance.recentTransactions — last 5 transactions

Analytics

const stats = await tokium.analytics.stats();
// stats.last30Days  — { totalSpent, totalFees, totalTransactions, successRate, ... }
// stats.allTime     — { totalSpent, totalFees, totalTransactions }

Platform Skill

const manifest = await tokium.skill();

Payments (Owner)

Requires bearer auth.

// Create a Stripe checkout session to fund an agent
const checkout = await tokium.payments.createCheckout({ agentId: 1, amount: 10 });
console.log(checkout.checkoutUrl); // redirect user here

// Check checkout status
const status = await tokium.payments.getCheckoutStatus(checkout.sessionId);
// status.status — 'open' | 'complete' | 'expired'

// Payment method management
await tokium.payments.setupPaymentMethod();    // returns { clientSecret, setupIntentId }
await tokium.payments.confirmPaymentMethod(setupIntentId);
const card = await tokium.payments.getPaymentMethod(); // { brand, last4, ... } or null
await tokium.payments.removePaymentMethod();

// Auto top-up
const settings = await tokium.payments.getAutoTopUp(agentId);
await tokium.payments.updateAutoTopUp(agentId, {
  enabled: true,
  threshold: 5,   // top up when balance drops below $5
  amount: 20,     // add $20 each time
});

Crypto (Owner)

Requires bearer auth.

// Get a deposit address
const addr = await tokium.crypto.getAddress({
  agentId: 1,
  chain: 'solana', // 'solana' | 'base' | 'ethereum'
});
console.log(addr.address, addr.minDeposit);

// List deposits
const { deposits, total } = await tokium.crypto.getDeposits({
  agentId: 1,
  chain: 'solana',
  page: 1,
  limit: 10,
});

// Check a specific deposit
const deposit = await tokium.crypto.getDepositStatus(txHash);

Error Handling

All API errors throw typed error classes:

import {
  TokiumError,
  InsufficientBalanceError,
  RateLimitError,
  ProxyError,
} from '@tokium-labs/sdk';

try {
  await tokium.proxies.call(42, { path: '/search' });
} catch (err) {
  if (err instanceof InsufficientBalanceError) {
    console.log(err.required, err.available);
  } else if (err instanceof RateLimitError) {
    console.log(err.retryAfter); // seconds
  } else if (err instanceof ProxyError) {
    console.log(err.httpStatus, err.responseTime);
  } else if (err instanceof TokiumError) {
    console.log(err.status, err.message);
  }
}

License

MIT