Skip to main content

TypeScript SDK

The Walleot TypeScript SDK enables you to integrate payment functionality into your MCP (Model Context Protocol) servers. This guide covers installation, initialization, pricing tools, and payment coordination modes.

Installation​

npm install walleot

Quick Start​

Here's how to get started with the TypeScript SDK in an MCP server:

import { Server } from "@modelcontextprotocol/sdk/server";
import { installWalleot, Mode } from "walleot";
import { z } from "zod";

// Initialize your MCP server
const server = new Server({ name: "my-server", version: "0.0.1" });

// Install Walleot with your API key
installWalleot(server, {
  apiKey: "YOUR WALLEOT API KEY",
  mode: Mode.TWO_STEP /* Mode.RESUBMIT / Mode.ELICITATION / Mode.PROGRESS / Mode.DYNAMIC_TOOLS */
});

// Register a priced tool
server.registerTool(
  "add_numbers",
  {
    title: "Add two numbers",
    description: "Adds two numbers and returns the sum.",
    inputSchema: { a: z.number(), b: z.number() },
    price: { amount: 0.19, currency: "USD" }, // $0.19 per call
  },
  async ({ a, b }, extra) => {
    return { content: [{ type: "text", text: String(a + b) }] };
  }
);

API Reference​

installWalleot Function​

The main function for integrating Walleot with your MCP server.

Function Signature​

installWalleot(
  server: Server,
  options: {
    apiKey: string;
    mode?: Mode;
  }
): void

Parameters:

  • server: Your MCP Server instance
  • options.apiKey: Your Walleot API key (get from dashboard)
  • options.mode: Mode (see Mode enum below)

Mode Enum​

Controls how your MCP Server and the MCP client coordinate the payment process.

import { Mode } from "walleot";

// Available options:
Mode.TWO_STEP       // Default
Mode.RESUBMIT
Mode.ELICITATION   
Mode.PROGRESS    
Mode.DYNAMIC_TOOLS

Tool Registration with Pricing​

Use the price property in your tool definition to set per-call pricing:

server.registerTool(
  "your_tool",
  {
    title: "Your Tool Title",
    description: "Your tool description.",
    inputSchema: { /* your schema */ },
    price: { amount: 0.25, currency: "USD" }, // $0.25 per call
  },
  async (args, extra) => {
    // Tool implementation
    return { content: [{ type: "text", text: "result" }] };
  }
);

Price Object:

  • amount: Price in dollars (e.g., 0.25 = $0.25)
  • currency: Currency code (default: "USD")

Examples​

Basic Math Tool​

import { Server } from "@modelcontextprotocol/sdk/server";
import { installWalleot, Mode } from "walleot";
import { z } from "zod";

const server = new Server({ name: "calculator", version: "1.0.0" });

installWalleot(server, {
  apiKey: process.env.WALLEOT_API_KEY!,
  mode: Mode.ELICITATION,
});

server.registerTool(
  "calculate",
  {
    title: "Basic Calculator",
    description: "Performs basic math operations.",
    inputSchema: {
      a: z.number(),
      b: z.number(),
      operation: z.enum(["add", "subtract", "multiply", "divide"]),
    },
    price: { amount: 0.10, currency: "USD" }, // $0.10 per calculation
  },
  async ({ a, b, operation }, extra) => {
    let result: number;
    
    switch (operation) {
      case "add":
        result = a + b;
        break;
      case "subtract":
        result = a - b;
        break;
      case "multiply":
        result = a * b;
        break;
      case "divide":
        result = b !== 0 ? a / b : 0;
        break;
      default:
        throw new Error("Invalid operation");
    }
    
    return { content: [{ type: "text", text: String(result) }] };
  }
);

Text Processing Tool​

server.registerTool(
  "process_text",
  {
    title: "Text Processor",
    description: "Processes text with various operations.",
    inputSchema: {
      text: z.string(),
      operation: z.enum(["uppercase", "lowercase", "reverse", "word_count"]),
    },
    price: { amount: 0.05, currency: "USD" }, // $0.05 per operation
  },
  async ({ text, operation }, extra) => {
    let result: string;
    
    switch (operation) {
      case "uppercase":
        result = text.toUpperCase();
        break;
      case "lowercase":
        result = text.toLowerCase();
        break;
      case "reverse":
        result = text.split("").reverse().join("");
        break;
      case "word_count":
        result = String(text.split(/\s+/).length);
        break;
      default:
        throw new Error("Invalid operation");
    }
    
    return { content: [{ type: "text", text: result }] };
  }
);

Environment Setup​

Required Environment Variables​

# .env file
WALLEOT_API_KEY=your_api_key_here

Loading Environment Variables​

import dotenv from "dotenv";

// Load .env file in development
dotenv.config();

// Access API key
const apiKey = process.env.WALLEOT_API_KEY;

TypeScript Configuration​

Ensure your tsconfig.json includes proper module resolution:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Best Practices​

  1. Use proper TypeScript types: Leverage Zod schemas for input validation
  2. Set appropriate prices: Consider the computational cost and value of your tools
  3. Handle errors gracefully: Implement proper error handling in your tools
  4. Use environment variables: Never hardcode API keys
  5. Test payment flows: Verify your payment flows work as expected
  6. Type your responses: Always return properly typed MCP responses

Next Steps​