Getting Started

1. Quick Start

Tokium gives your AI agents a wallet so they can call any paid API autonomously. No individual API keys, no subscriptions — just fund a wallet and let your agent work.

1. Create an account — sign up at tokium.xyz or run tokium register from the CLI.
2. Create an agent — each agent gets its own API key and wallet.
3. Fund the wallet — add funds via Stripe (card) or USDC (crypto).
4. Start calling APIs — your agent pays per request, automatically.

2. Which Tool Should I Use?

Tokium offers multiple ways to integrate, depending on how you work. Here's a quick guide:

3. Dashboard

The dashboard is the web UI for managing your Tokium account:

• Agents — Create agents, view API keys, set spending limits.
• Wallets — Fund agent wallets via Stripe or USDC. Set up auto top-up.
• Marketplace — Browse available API proxies, read docs, see pricing.
• Usage — Monitor API calls, spending, and transaction history per agent.

4. CLI

The Tokium CLI lets you manage your account from the terminal. Install it globally:

npm install -g @tokium-labs/cli

Or run directly without installing:

npx @tokium-labs/cli status

Common commands

# Login to your account
tokium login

# See your account and all agents
tokium status

# Create an agent (prints the API key once — save it!)
tokium agents create my-agent

# Fund an agent with $10
tokium top-up 42 10

# Check an agent's balance
tokium balance 42

# Browse and search the API marketplace
tokium proxies list
tokium proxies search "web scraping"

# Call a proxy directly from the terminal
tokium proxies call 7 --path /search --method POST --body '{"q":"test"}'

# Logout
tokium logout

Run tokium --help or tokium agents --help for the full list of commands and options. See the full CLI docs on npm.

5. TypeScript SDK

The SDK is for when you're writing code that calls APIs programmatically — building a custom agent, a backend service, or anything in Node.js / Deno / Bun.

npm install @tokium-labs/sdk

Agent mode — call APIs from your code

Use your agent's API key. This is what your agent code uses to discover and call APIs.

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

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

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

// Call a proxy — payment happens automatically
const result = await tokium.proxies.call(42, {
  method: "POST",
  path: "/people/search",
  body: { query: "CEO at Acme" },
});

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

// Check your balance
const balance = await tokium.wallets.balance();
console.log(balance.agent.balance);  // "$47.23"

Owner mode — manage agents and payments

Use your account credentials to create agents, fund wallets, and manage settings. Useful for admin scripts and dashboards.

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

// Login with your account
const tokium = await Tokium.login({
  email: "[email protected]",
  password: "...",
});

// Create an agent
const agent = await tokium.agents.create({ name: "my-agent" });
console.log(agent.apiKey);  // Save this — shown only once

// Fund it via Stripe
const checkout = await tokium.payments.createCheckout({
  agentId: agent.agentId,
  amount: 25,
});
console.log(checkout.checkoutUrl);  // Open to pay

// Set up auto top-up so it never runs dry
await tokium.payments.updateAutoTopUp(agent.agentId, {
  enabled: true,
  threshold: 5,   // When balance drops below $5...
  amount: 20,     // ...add $20 automatically
});

// List all your agents
const agents = await tokium.agents.list();

Error handling

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

try {
  await tokium.proxies.call(42, { path: "/search" });
} catch (err) {
  if (err instanceof InsufficientBalanceError) {
    console.log("Not enough funds:", err.available);
  } else if (err instanceof RateLimitError) {
    console.log("Slow down, retry in", err.retryAfter, "seconds");
  } else if (err instanceof TokiumError) {
    console.log("API error:", err.status, err.message);
  }
}

Zero dependencies. Works in Node 18+, Deno, Bun, and edge runtimes. See the full API reference on npm.

6. MCP Server

The MCP server gives AI tools native access to Tokium — no code needed from you. Once configured, your AI assistant can discover APIs, call them, check balances, and even manage agents on its own.

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "tokium": {
      "command": "npx",
      "args": ["-y", "@tokium-labs/mcp"],
      "env": {
        "TOKIUM_API_KEY": "sk-live-..."
      }
    }
  }
}

Claude Code

Add a .mcp.json file to your project root:

{
  "mcpServers": {
    "tokium": {
      "command": "npx",
      "args": ["-y", "@tokium-labs/mcp"],
      "env": {
        "TOKIUM_API_KEY": "sk-live-..."
      }
    }
  }
}

Cursor / Windsurf

Add to your MCP settings (.cursor/mcp.json or .windsurf/mcp.json):

{
  "mcpServers": {
    "tokium": {
      "command": "npx",
      "args": ["-y", "@tokium-labs/mcp"],
      "env": {
        "TOKIUM_API_KEY": "sk-live-..."
      }
    }
  }
}

Owner tools (optional)

Want the AI to also manage agents and fund wallets? Add your account credentials:

{
  "mcpServers": {
    "tokium": {
      "command": "npx",
      "args": ["-y", "@tokium-labs/mcp"],
      "env": {
        "TOKIUM_API_KEY": "sk-live-...",
        "TOKIUM_EMAIL": "[email protected]",
        "TOKIUM_PASSWORD": "..."
      }
    }
  }
}

Available tools

After restarting, your AI gets these tools:

See the full MCP server docs on npm.

7. skill.md

If your agent doesn't support MCP, you can give it the Tokium skill file instead. It's a markdown document that teaches any LLM how to use the Tokium REST API directly — including authentication, available endpoints, and example calls.

Paste the contents of tokium.xyz/skill.md into your agent's system prompt, instructions file, or CLAUDE.md.

# In your agent's system prompt or instructions:

Fetch the contents of https://tokium.xyz/skill.md
and use it to interact with the Tokium API.

Your API key: sk-live-...

This works with LangChain, CrewAI, AutoGPT, OpenAI Agents, and any other LLM framework that supports function calling or tool use.

View skill.md