@swap-coffee/ai-tools

Production-ready Vercel AI SDK (v6+) tools for swap.coffee.

This package provides:

• Full tool coverage for swap.coffee backend OpenAPI (https://backend.swap.coffee/openapi)
• Full tool coverage for tokens OpenAPI (https://tokens.swap.coffee/api/v3/openapi.yaml)
• Grouped tool access by OpenAPI tags (for controlled agent capabilities)
• Individual tool access by tool name
• SDK utility tools on top of @swap-coffee/sdk

Installation

npm install @swap-coffee/ai-tools ai @swap-coffee/sdk zod

Quick Start

import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { createSwapCoffeeTools } from '@swap-coffee/ai-tools';

const tools = createSwapCoffeeTools({
  client: {
    backend: {
      apiKey: process.env.SWAP_COFFEE_API_KEY,
    },
    tokens: {
      apiKey: process.env.SWAP_COFFEE_API_KEY,
    },
  },
  // Optional filtering:
  // includeServices: ['backend'],
  // includeTags: ['Routing'],
  // includeToolNames: ['backend_buildRoute'],
});

const result = await generateText({
  model: openai(process.env.AI_MODEL!),
  prompt: 'Find available TON staking pools and explain top options.',
  tools,
});

console.log(result.text);

Tool Selection Modes

1) Use tools one-by-one

const tools = createSwapCoffeeTools({
  client,
  includeToolNames: ['backend_buildRoute', 'backend_buildTransactionsV2'],
});

2) Use tool groups by domain

import { createSwapCoffeeToolGroups } from '@swap-coffee/ai-tools';

const groups = createSwapCoffeeToolGroups({ client });

const routingTools = {
  ...(groups['backend:Routing'] ?? {}),
  ...(groups['sdk:utilities'] ?? {}),
};

3) Inspect all available tools

import { getSwapCoffeeToolCatalog } from '@swap-coffee/ai-tools';

const catalog = getSwapCoffeeToolCatalog();
console.log(catalog.length);
console.log(catalog.slice(0, 10));

Included SDK Utility Tools

• sdk_wait_for_route_results: wraps waitForRouteResults from @swap-coffee/sdk

Examples

See examples/single-tool.ts, examples/grouped-tools.ts, and examples/catalog.ts.

Development

npm run generate
npm run typecheck
npm run build
npm test

Notes

• OpenAPI operation tools are generated from local snapshots in specs/tokens.openapi.yaml and specs/backend.openapi.json.
• Re-run npm run generate to refresh tool metadata when APIs change.