@ton-agent-kit/core 1.0.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ton-agent-kit/core",
+  "version": "1.0.0",
+  "description": "Core SDK for TON Agent Kit — plugin system, wallet abstraction, agent class",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  },
+  "dependencies": {
+    "@ton/ton": "^16.2.0",
+    "@ton/core": "^0.63.1",
+    "@ton/crypto": "^3.3.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@ton/sandbox": "^0.20.0"
+  },
+  "peerDependencies": {
+    "@ton/ton": ">=14.0.0",
+    "@ton/core": ">=0.63.0"
+  },
+  "keywords": ["ton", "blockchain", "ai", "agent", "sdk"],
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "repository": { "type": "git", "url": "https://github.com/Andy00L/ton-agent-kit.git" }
+}

package/src/agent.ts

@@ -0,0 +1,399 @@
+import { readFileSync } from "fs";
+import { TonClient4 } from "@ton/ton";
+import { PluginRegistry } from "./plugin";
+import type {
+  Action,
+  AgentContext,
+  Plugin,
+  TonAgentKitConfig,
+  TonNetwork,
+  WalletProvider,
+} from "./types";
+import { RPC_ENDPOINTS } from "./utils";
+import { KeypairWallet } from "./wallet";
+
+export interface RunLoopOptions {
+  maxIterations?: number;
+  provider?: "openai";
+  model?: string;
+  apiKey?: string;
+  baseURL?: string;
+  verbose?: boolean;
+  /** Called at the start of each LLM iteration */
+  onIteration?: (iteration: number, maxIterations: number) => void;
+  /** Called before an action is executed */
+  onActionStart?: (actionName: string, params: any) => void;
+  /** Called after an action returns */
+  onActionResult?: (actionName: string, params: any, result: any) => void;
+  /** Called when the agent finishes (no more tool calls) */
+  onComplete?: () => void;
+}
+
+export interface RunLoopResult {
+  goal: string;
+  steps: Array<{ action: string; params: any; result: any }>;
+  summary: string;
+}
+
+/** Read a key from .env file (fallback when dotenv doesn't load) */
+function readEnvKey(key: string): string {
+  try {
+    return readFileSync(".env", "utf-8")
+      .split("\n")
+      .find((l) => l.startsWith(key + "="))
+      ?.slice(key.length + 1)
+      .trim() || "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * TonAgentKit — the main entry point for connecting AI agents to TON.
+ *
+ * @example
+ * ```ts
+ * const wallet = await KeypairWallet.fromMnemonic(mnemonic, {
+ *   version: "V5R1",
+ *   network: "testnet",
+ * });
+ * const agent = new TonAgentKit(wallet, "https://testnet-v4.tonhubapi.com")
+ *   .use(TokenPlugin)
+ *   .use(DefiPlugin);
+ *
+ * const balance = await agent.runAction("get_balance", {});
+ * ```
+ */
+export class TonAgentKit {
+  public readonly wallet: WalletProvider;
+  public readonly connection: TonClient4;
+  public readonly network: TonNetwork;
+  public readonly rpcUrl: string;
+  public readonly config: TonAgentKitConfig;
+  public readonly methods: Record<string, (params: any) => Promise<any>>;
+
+  private registry: PluginRegistry;
+  private context: AgentContext;
+  private initialized: boolean = false;
+
+  constructor(
+    wallet: WalletProvider,
+    rpcUrl?: string,
+    config?: TonAgentKitConfig,
+    network?: TonNetwork,
+  ) {
+    this.wallet = wallet;
+    this.network =
+      network || (rpcUrl?.includes("testnet") ? "testnet" : "mainnet");
+    this.rpcUrl = rpcUrl || RPC_ENDPOINTS[this.network];
+    this.config = config || {};
+    this.registry = new PluginRegistry();
+
+    // Create TON client
+    this.connection = new TonClient4({ endpoint: this.rpcUrl });
+
+    // If wallet supports setClient, inject the connection
+    if (wallet instanceof KeypairWallet) {
+      wallet.setClient(this.rpcUrl);
+    }
+
+    // Create agent context
+    this.context = {
+      connection: this.connection,
+      wallet: this.wallet,
+      network: this.network,
+      rpcUrl: this.rpcUrl,
+      config: this.config as Record<string, string>,
+    };
+
+    // Create methods proxy for convenient access
+    this.methods = new Proxy(
+      {} as Record<string, (params: any) => Promise<any>>,
+      {
+        get: (_target, prop: string) => {
+          return (params: any) => this.runAction(prop, params);
+        },
+      },
+    );
+  }
+
+  /**
+   * Quick factory: create agent from mnemonic with auto-detect wallet version
+   */
+  static async fromMnemonic(
+    mnemonic: string[],
+    rpcUrl?: string,
+    config?: TonAgentKitConfig,
+    network?: TonNetwork,
+  ): Promise<TonAgentKit> {
+    const net =
+      network || (rpcUrl?.includes("testnet") ? "testnet" : "mainnet");
+    const url = rpcUrl || RPC_ENDPOINTS[net];
+    const client = new TonClient4({ endpoint: url });
+
+    const wallet = await KeypairWallet.autoDetect(mnemonic, client, net);
+    return new TonAgentKit(wallet, url, config, net);
+  }
+
+  // ============================================================
+  // Plugin Management
+  // ============================================================
+
+  use(plugin: Plugin): this {
+    this.registry.register(plugin);
+    return this;
+  }
+
+  // ============================================================
+  // Action Execution
+  // ============================================================
+
+  async runAction<TOutput = any>(
+    actionName: string,
+    params: any,
+  ): Promise<TOutput> {
+    if (!this.initialized) {
+      await this.initializePlugins();
+      this.initialized = true;
+    }
+
+    const action = this.registry.getAction(actionName);
+    if (!action) {
+      const available = this.getAvailableActions()
+        .map((a) => a.name)
+        .join(", ");
+      throw new Error(
+        `Action "${actionName}" not found. Available: ${available}`,
+      );
+    }
+
+    const parsed = action.schema.safeParse(params);
+    if (!parsed.success) {
+      throw new Error(
+        `Invalid params for "${actionName}": ${parsed.error.message}`,
+      );
+    }
+
+    try {
+      return await action.handler(this.context, parsed.data);
+    } catch (err) {
+      const error = err as Error;
+      throw new Error(`Action "${actionName}" failed: ${error.message}`);
+    }
+  }
+
+  // ============================================================
+  // Introspection
+  // ============================================================
+
+  getAvailableActions(): Action[] {
+    return this.registry.getAllActions();
+  }
+
+  getPlugins(): Plugin[] {
+    return this.registry.getAllPlugins();
+  }
+
+  get actionCount(): number {
+    return this.registry.actionCount;
+  }
+
+  get address(): string {
+    return this.wallet.address.toString();
+  }
+
+  // ============================================================
+  // Autonomous Agent Loop
+  // ============================================================
+
+  async runLoop(
+    goal: string,
+    options?: RunLoopOptions,
+  ): Promise<RunLoopResult> {
+    const maxIterations = options?.maxIterations ?? 5;
+    const model = options?.model || process.env.AI_MODEL || "gpt-4.1-nano";
+    const apiKey = options?.apiKey || process.env.OPENAI_API_KEY || readEnvKey("OPENAI_API_KEY");
+    const baseURL = options?.baseURL || process.env.OPENAI_BASE_URL;
+    const verbose = options?.verbose ?? true;
+
+    if (!apiKey) {
+      throw new Error(
+        "runLoop requires an AI provider API key. Set OPENAI_API_KEY in .env",
+      );
+    }
+
+    // Dynamic imports so the SDK works without these deps installed
+    const { default: OpenAI } = await import("openai");
+    const { toJSONSchema } = await import("zod");
+    const client = new OpenAI({ apiKey, baseURL });
+
+    // Ensure plugins are initialized
+    if (!this.initialized) {
+      await this.initializePlugins();
+      this.initialized = true;
+    }
+
+    // Build OpenAI tools from available actions
+    const actions = this.getAvailableActions();
+    const tools: Array<{
+      type: "function";
+      function: { name: string; description: string; parameters: any };
+    }> = actions.map((action) => ({
+      type: "function" as const,
+      function: {
+        name: action.name,
+        description: action.description,
+        parameters: (() => {
+            const { $schema, ...schema } = toJSONSchema(action.schema);
+            return schema;
+          })(),
+      },
+    }));
+
+    // Build system prompt
+    const actionList = actions
+      .map((a) => {
+        const jsonSchema = toJSONSchema(a.schema) as any;
+        const paramNames = JSON.stringify(Object.keys(jsonSchema.properties || {}));
+        return `- ${a.name}: ${a.description}\n  Parameters: ${paramNames}`;
+      })
+      .join("\n");
+    const systemPrompt = `You are an autonomous AI agent with a TON blockchain wallet. You have access to the following actions:\n${actionList}\n\nIMPORTANT: When calling functions, use EXACTLY the parameter names listed above. Do NOT rename parameters (e.g. use "to" not "destination", "token" not "token_address").\n\nExecute the user's goal by calling the appropriate actions. When done, provide a summary of what you accomplished.`;
+
+    const messages: Array<any> = [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: goal },
+    ];
+
+    const steps: Array<{ action: string; params: any; result: any }> = [];
+
+    for (let i = 0; i < maxIterations; i++) {
+      if (options?.onIteration) {
+        options.onIteration(i + 1, maxIterations);
+      } else if (verbose) {
+        console.log(`\n🔄 Iteration ${i + 1}/${maxIterations}`);
+      }
+
+      const response = await client.chat.completions.create({
+        model,
+        messages,
+        tools,
+      });
+
+      const choice = response.choices[0];
+      if (!choice.message) break;
+
+      messages.push(choice.message);
+
+      // If no tool calls, the LLM is done
+      if (
+        !choice.message.tool_calls ||
+        choice.message.tool_calls.length === 0
+      ) {
+        if (options?.onComplete) {
+          options.onComplete();
+        } else if (verbose) {
+          console.log("✅ Agent finished reasoning");
+        }
+        return {
+          goal,
+          steps,
+          summary: choice.message.content || "Goal completed.",
+        };
+      }
+
+      // Execute each tool call
+      for (const toolCall of choice.message.tool_calls as any[]) {
+        const actionName = toolCall.function.name;
+        let params: any;
+        try {
+          params = JSON.parse(toolCall.function.arguments);
+        } catch {
+          params = {};
+        }
+
+        // Remap misnamed parameters to match the action schema
+        const matchedAction = actions.find((a) => a.name === actionName);
+        if (matchedAction) {
+          const expectedSchema = toJSONSchema(matchedAction.schema) as any;
+          const expectedKeys = new Set(Object.keys(expectedSchema.properties || {}));
+          const paramKeys = Object.keys(params);
+          for (const key of paramKeys) {
+            if (!expectedKeys.has(key)) {
+              // Find a matching expected key that isn't already provided
+              for (const expected of expectedKeys) {
+                if (!(expected in params) && key.toLowerCase().includes(expected.toLowerCase())) {
+                  params[expected] = params[key];
+                  delete params[key];
+                  break;
+                }
+              }
+            }
+          }
+        }
+
+        if (options?.onActionStart) {
+          options.onActionStart(actionName, params);
+        } else if (verbose) {
+          console.log(`  ▶ ${actionName}(${JSON.stringify(params)})`);
+        }
+
+        let result: any;
+        try {
+          result = await this.runAction(actionName, params);
+        } catch (err) {
+          result = { error: (err as Error).message };
+        }
+
+        if (options?.onActionResult) {
+          options.onActionResult(actionName, params, result);
+        } else if (verbose) {
+          console.log(
+            `  ◀ ${typeof result === "string" ? result : JSON.stringify(result)}`,
+          );
+        }
+
+        steps.push({ action: actionName, params, result });
+
+        messages.push({
+          role: "tool",
+          tool_call_id: toolCall.id,
+          content:
+            typeof result === "string" ? result : JSON.stringify(result),
+        });
+      }
+    }
+
+    // Max iterations reached — ask LLM for a final summary
+    messages.push({
+      role: "user",
+      content:
+        "Max iterations reached. Summarize what you accomplished so far.",
+    });
+
+    const finalResponse = await client.chat.completions.create({
+      model,
+      messages,
+    });
+
+    return {
+      goal,
+      steps,
+      summary:
+        finalResponse.choices[0]?.message?.content ||
+        `Completed ${steps.length} steps.`,
+    };
+  }
+
+  // ============================================================
+  // Internal
+  // ============================================================
+
+  private async initializePlugins(): Promise<void> {
+    for (const plugin of this.registry.getAllPlugins()) {
+      if (plugin.initialize) {
+        await plugin.initialize(this.context);
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// ============================================================
+// @ton-agent-kit/core
+// Connect any AI agent to TON protocols
+// ============================================================
+
+export { TonAgentKit } from "./agent";
+export type { RunLoopOptions, RunLoopResult } from "./agent";
+export { defineAction, definePlugin, PluginRegistry } from "./plugin";
+export { KeypairWallet, ReadOnlyWallet } from "./wallet";
+export type { WalletConfig, WalletVersion } from "./wallet";
+
+export type {
+  Action,
+  AgentContext,
+  BalanceResult,
+  DnsInfo,
+  JettonBalanceResult,
+  JettonInfo,
+  NftInfo,
+  Plugin,
+  SwapResult,
+  TonAgentKitConfig,
+  TonNetwork,
+  TransactionResult,
+  WalletProvider,
+} from "./types";
+
+export {
+  explorerAddressUrl,
+  explorerUrl,
+  nanoToTon,
+  parseAddress,
+  retry,
+  RPC_ENDPOINTS,
+  sendTransaction,
+  sleep,
+  toFriendlyAddress,
+  TONCENTER_ENDPOINTS,
+  tonToNano,
+} from "./utils";

package/src/plugin.ts

@@ -0,0 +1,89 @@
+import type { Plugin, Action } from "./types";
+
+/**
+ * Plugin registry — manages action registration and lookup.
+ */
+export class PluginRegistry {
+  private plugins: Map<string, Plugin> = new Map();
+  private actions: Map<string, Action> = new Map();
+
+  /**
+   * Register a plugin and all its actions
+   */
+  register(plugin: Plugin): void {
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`Plugin "${plugin.name}" is already registered.`);
+    }
+
+    // Check for action name conflicts
+    for (const action of plugin.actions) {
+      if (this.actions.has(action.name)) {
+        throw new Error(
+          `Action "${action.name}" from plugin "${plugin.name}" conflicts with an existing action.`
+        );
+      }
+    }
+
+    // Register plugin and its actions
+    this.plugins.set(plugin.name, plugin);
+    for (const action of plugin.actions) {
+      this.actions.set(action.name, action);
+    }
+  }
+
+  /**
+   * Get an action by name
+   */
+  getAction(name: string): Action | undefined {
+    return this.actions.get(name);
+  }
+
+  /**
+   * Get all registered actions
+   */
+  getAllActions(): Action[] {
+    return Array.from(this.actions.values());
+  }
+
+  /**
+   * Get all registered plugins
+   */
+  getAllPlugins(): Plugin[] {
+    return Array.from(this.plugins.values());
+  }
+
+  /**
+   * Check if a plugin is registered
+   */
+  hasPlugin(name: string): boolean {
+    return this.plugins.has(name);
+  }
+
+  /**
+   * Get action count
+   */
+  get actionCount(): number {
+    return this.actions.size;
+  }
+
+  /**
+   * Get plugin count
+   */
+  get pluginCount(): number {
+    return this.plugins.size;
+  }
+}
+
+/**
+ * Helper to define a plugin with type safety
+ */
+export function definePlugin(plugin: Plugin): Plugin {
+  return plugin;
+}
+
+/**
+ * Helper to define an action with type safety
+ */
+export function defineAction<TInput, TOutput>(action: Action<TInput, TOutput>): Action<TInput, TOutput> {
+  return action;
+}

package/src/types.ts

@@ -0,0 +1,169 @@
+import type { Address, MessageRelaxed } from "@ton/core";
+import type { TonClient, TonClient4 } from "@ton/ton";
+import { z } from "zod";
+
+// ============================================================
+// Wallet Provider
+// ============================================================
+
+export interface WalletProvider {
+  /** The wallet's address on TON */
+  address: Address;
+  /** Send one or more messages (the reliable way to transact on TON) */
+  sendTransfer(messages: MessageRelaxed[]): Promise<void>;
+  /** Sign arbitrary data (optional, for identity proofs) */
+  sign?(data: Buffer): Promise<Buffer>;
+}
+
+// ============================================================
+// Action — a single autonomous operation an agent can perform
+// ============================================================
+
+export interface Action<TInput = any, TOutput = any> {
+  /** Unique identifier, e.g. "transfer_ton" */
+  name: string;
+  /** Human-readable description (used as LLM tool description) */
+  description: string;
+  /** Zod schema for validating and describing inputs */
+  schema: z.ZodType<TInput>;
+  /** Execute the action */
+  handler: (agent: AgentContext, params: TInput) => Promise<TOutput>;
+  /** Optional examples for better LLM understanding */
+  examples?: Array<{
+    input: TInput;
+    output: TOutput;
+    description?: string;
+  }>;
+}
+
+// ============================================================
+// Plugin — a collection of related actions
+// ============================================================
+
+export interface Plugin {
+  /** Plugin name, e.g. "token", "defi" */
+  name: string;
+  /** Actions provided by this plugin */
+  actions: Action[];
+  /** Optional initialization hook */
+  initialize?: (agent: AgentContext) => Promise<void>;
+}
+
+// ============================================================
+// Agent Context — what actions receive to interact with TON
+// ============================================================
+
+export interface AgentContext {
+  /** TON blockchain client */
+  connection: TonClient4 | TonClient;
+  /** Wallet provider for signing transactions */
+  wallet: WalletProvider;
+  /** Network: mainnet or testnet */
+  network: TonNetwork;
+  /** RPC endpoint URL */
+  rpcUrl: string;
+  /** Optional config (API keys, etc.) */
+  config: Record<string, string>;
+}
+
+// ============================================================
+// Agent Kit Configuration
+// ============================================================
+
+export interface TonAgentKitConfig {
+  /** Optional API keys for LLMs or services */
+  OPENAI_API_KEY?: string;
+  TONAPI_KEY?: string;
+  [key: string]: string | undefined;
+}
+
+export type TonNetwork = "mainnet" | "testnet";
+
+// ============================================================
+// Action Result Types
+// ============================================================
+
+export interface TransactionResult {
+  /** Transaction hash */
+  txHash: string;
+  /** Human-readable status */
+  status: "sent" | "confirmed" | "failed";
+  /** Optional explorer link */
+  explorerUrl?: string;
+  /** Fee paid */
+  fee?: string;
+}
+
+export interface BalanceResult {
+  /** Balance in TON (human-readable) */
+  balance: string;
+  /** Balance in nanoton */
+  balanceRaw: string;
+  /** Address queried */
+  address: string;
+}
+
+export interface JettonBalanceResult {
+  /** Balance in token units */
+  balance: string;
+  /** Balance in raw units */
+  balanceRaw: string;
+  /** Token symbol */
+  symbol: string;
+  /** Token name */
+  name: string;
+  /** Decimals */
+  decimals: number;
+}
+
+export interface SwapResult extends TransactionResult {
+  /** Amount sent */
+  fromAmount: string;
+  /** Token sent */
+  fromToken: string;
+  /** Amount received (estimated) */
+  toAmount: string;
+  /** Token received */
+  toToken: string;
+  /** DEX used */
+  dex: "dedust" | "stonfi";
+}
+
+export interface JettonInfo {
+  /** Jetton master address */
+  address: string;
+  /** Token name */
+  name: string;
+  /** Token symbol */
+  symbol: string;
+  /** Decimals */
+  decimals: number;
+  /** Total supply */
+  totalSupply: string;
+  /** Description */
+  description?: string;
+  /** Image URL */
+  image?: string;
+}
+
+export interface NftInfo {
+  /** NFT address */
+  address: string;
+  /** NFT index in collection */
+  index: number;
+  /** Owner address */
+  owner: string;
+  /** Collection address */
+  collection?: string;
+  /** Metadata */
+  metadata?: Record<string, any>;
+}
+
+export interface DnsInfo {
+  /** Domain name */
+  domain: string;
+  /** Resolved address */
+  address?: string;
+  /** Expiration timestamp */
+  expiresAt?: number;
+}

package/src/utils.ts

@@ -0,0 +1,133 @@
+import { Address, fromNano, toNano, type MessageRelaxed } from "@ton/core";
+import { TonClient4, WalletContractV5R1 } from "@ton/ton";
+import type { AgentContext } from "./types";
+
+/**
+ * Convert TON amount string to nanoton bigint
+ */
+export function tonToNano(amount: string): bigint {
+  return toNano(amount);
+}
+
+/**
+ * Convert nanoton bigint to human-readable TON string
+ */
+export function nanoToTon(amount: bigint | string): string {
+  return fromNano(typeof amount === "string" ? BigInt(amount) : amount);
+}
+
+/**
+ * Parse address string to Address object (supports both raw and user-friendly)
+ */
+export function parseAddress(address: string): Address {
+  return Address.parse(address);
+}
+
+/**
+ * Convert address to user-friendly format (non-bounceable, like Tonkeeper)
+ */
+export function toFriendlyAddress(address: Address, network: "testnet" | "mainnet" = "mainnet"): string {
+  return address.toString({ testOnly: network === "testnet", bounceable: false });
+}
+
+/**
+ * Generate TON explorer URL for a transaction
+ */
+export function explorerUrl(
+  txHash: string,
+  network: "mainnet" | "testnet" = "mainnet"
+): string {
+  const base = network === "testnet"
+    ? "https://testnet.tonviewer.com"
+    : "https://tonviewer.com";
+  return `${base}/transaction/${txHash}`;
+}
+
+/**
+ * Generate TON explorer URL for an address
+ */
+export function explorerAddressUrl(
+  address: string,
+  network: "mainnet" | "testnet" = "mainnet"
+): string {
+  const base = network === "testnet"
+    ? "https://testnet.tonviewer.com"
+    : "https://tonviewer.com";
+  return `${base}/${address}`;
+}
+
+/**
+ * Wait for a specified number of milliseconds
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Retry an async operation with exponential backoff
+ */
+export async function retry<T>(
+  fn: () => Promise<T>,
+  maxRetries: number = 3,
+  baseDelay: number = 1000
+): Promise<T> {
+  let lastError: Error | undefined;
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err as Error;
+      if (i < maxRetries - 1) {
+        await sleep(baseDelay * Math.pow(2, i));
+      }
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * Send a transaction using the proven WalletContractV5R1 pattern.
+ * This bypasses KeypairWallet.sendTransfer() which hits a domainSign
+ * incompatibility in certain @ton/ton versions.
+ */
+export async function sendTransaction(
+  agent: AgentContext,
+  messages: MessageRelaxed[],
+): Promise<void> {
+  const { secretKey, publicKey } = (agent.wallet as any).getCredentials();
+  const networkId = agent.network === "testnet" ? -3 : -239;
+  const freshClient = new TonClient4({ endpoint: agent.rpcUrl });
+  const walletContract = freshClient.open(
+    WalletContractV5R1.create({
+      workchain: 0,
+      publicKey,
+      walletId: {
+        networkGlobalId: networkId,
+        workchain: 0,
+        subwalletNumber: 0,
+      },
+    }),
+  );
+  const seqno = await walletContract.getSeqno();
+  await walletContract.sendTransfer({
+    seqno,
+    secretKey,
+    messages,
+  });
+}
+
+/**
+ * Default RPC endpoints
+ */
+export const RPC_ENDPOINTS = {
+  mainnet: "https://mainnet-v4.tonhubapi.com",
+  testnet: "https://testnet-v4.tonhubapi.com",
+} as const;
+
+/**
+ * Default TonCenter API endpoints
+ */
+export const TONCENTER_ENDPOINTS = {
+  mainnet: "https://toncenter.com/api/v2/jsonRPC",
+  testnet: "https://testnet.toncenter.com/api/v2/jsonRPC",
+} as const;

package/src/wallet.ts

@@ -0,0 +1,204 @@
+import { Address, type MessageRelaxed } from "@ton/core";
+import { KeyPair, mnemonicToPrivateKey } from "@ton/crypto";
+import {
+  TonClient4,
+  WalletContractV3R2,
+  WalletContractV4,
+  WalletContractV5R1,
+} from "@ton/ton";
+import type { WalletProvider } from "./types";
+
+export type WalletVersion = "V3R2" | "V4" | "V5R1";
+
+export interface WalletConfig {
+  version?: WalletVersion;
+  workchain?: number;
+  network?: "testnet" | "mainnet";
+  subwalletNumber?: number;
+}
+
+const NETWORK_IDS = {
+  testnet: -3,
+  mainnet: -239,
+} as const;
+
+function createWalletContract(publicKey: Buffer, config: WalletConfig = {}) {
+  const version = config.version || "V5R1";
+  const workchain = config.workchain || 0;
+  const network = config.network || "mainnet";
+
+  switch (version) {
+    case "V3R2":
+      return WalletContractV3R2.create({ workchain, publicKey });
+    case "V4":
+      return WalletContractV4.create({ workchain, publicKey });
+    case "V5R1":
+      return WalletContractV5R1.create({
+        workchain,
+        publicKey,
+        walletId: {
+          networkGlobalId: NETWORK_IDS[network],
+          workchain,
+          subwalletNumber: config.subwalletNumber ?? 0,
+        },
+      });
+    default:
+      throw new Error(`Unsupported wallet version: ${version}`);
+  }
+}
+
+export class KeypairWallet implements WalletProvider {
+  public address: Address;
+  public readonly version: WalletVersion;
+  private keyPair: KeyPair;
+  private walletConfig: WalletConfig;
+  private rpcUrl: string = "";
+
+  private constructor(keyPair: KeyPair, config: WalletConfig) {
+    this.keyPair = keyPair;
+    this.walletConfig = config;
+    this.version = config.version || "V5R1";
+    const contract = createWalletContract(keyPair.publicKey, config);
+    this.address = contract.address;
+  }
+
+  static async fromMnemonic(
+    mnemonic: string[],
+    config: WalletConfig = {},
+  ): Promise<KeypairWallet> {
+    const keyPair = await mnemonicToPrivateKey(mnemonic);
+    return new KeypairWallet(keyPair, config);
+  }
+
+  static fromSecretKey(
+    secretKey: Buffer,
+    config: WalletConfig = {},
+  ): KeypairWallet {
+    const publicKey = secretKey.subarray(32);
+    const keyPair: KeyPair = { secretKey, publicKey };
+    return new KeypairWallet(keyPair, config);
+  }
+
+  static async autoDetect(
+    mnemonic: string[],
+    client: TonClient4,
+    network: "testnet" | "mainnet" = "mainnet",
+  ): Promise<KeypairWallet> {
+    const keyPair = await mnemonicToPrivateKey(mnemonic);
+    const versions: WalletVersion[] = ["V5R1", "V4", "V3R2"];
+    const lastBlock = await client.getLastBlock();
+
+    for (const version of versions) {
+      const config: WalletConfig = { version, network };
+      const contract = createWalletContract(keyPair.publicKey, config);
+
+      try {
+        const state = await client.getAccount(
+          lastBlock.last.seqno,
+          contract.address,
+        );
+        if (state.account.balance.coins > 0n) {
+          console.error(
+            `Auto-detected wallet: ${version} (${contract.address.toString({ testOnly: network === "testnet", bounceable: false })})`,
+          );
+          return new KeypairWallet(keyPair, config);
+        }
+      } catch {
+        // Skip
+      }
+    }
+
+    console.error("No existing wallet found, defaulting to V5R1");
+    return new KeypairWallet(keyPair, { version: "V5R1", network });
+  }
+
+  /**
+   * Set the RPC URL — called by TonAgentKit on init
+   */
+  setClient(rpcUrl: string): void {
+    this.rpcUrl = rpcUrl;
+  }
+
+  /**
+   * Send messages using a fresh client every time.
+   * This is the proven pattern that works on both testnet and mainnet.
+   */
+  async sendTransfer(messages: MessageRelaxed[]): Promise<void> {
+    if (!this.rpcUrl) {
+      throw new Error(
+        "RPC URL not set. Let TonAgentKit handle initialization.",
+      );
+    }
+
+    const freshClient = new TonClient4({ endpoint: this.rpcUrl });
+    const freshContract = createWalletContract(
+      this.keyPair.publicKey,
+      this.walletConfig,
+    );
+    const contract = freshClient.open(freshContract);
+
+    const seqno = await contract.getSeqno();
+
+    await contract.sendTransfer({
+      seqno,
+      secretKey: this.keyPair.secretKey,
+      messages,
+    });
+  }
+
+  /**
+   * Get the raw materials for handlers that need direct contract access.
+   * Returns everything needed to call sendTransfer on a fresh contract.
+   */
+  getCredentials(): {
+    secretKey: Buffer;
+    publicKey: Buffer;
+    walletConfig: WalletConfig;
+  } {
+    return {
+      secretKey: this.keyPair.secretKey,
+      publicKey: this.keyPair.publicKey,
+      walletConfig: this.walletConfig,
+    };
+  }
+
+  async sign(data: Buffer): Promise<Buffer> {
+    const { sign } = await import("@ton/crypto");
+    return sign(data, this.keyPair.secretKey);
+  }
+
+  static async getAllAddresses(
+    mnemonic: string[],
+    network: "testnet" | "mainnet" = "mainnet",
+  ): Promise<Record<WalletVersion, string>> {
+    const keyPair = await mnemonicToPrivateKey(mnemonic);
+    const versions: WalletVersion[] = ["V3R2", "V4", "V5R1"];
+    const result: Record<string, string> = {};
+
+    for (const version of versions) {
+      const contract = createWalletContract(keyPair.publicKey, {
+        version,
+        network,
+      });
+      result[version] = contract.address.toString({
+        testOnly: network === "testnet",
+        bounceable: false,
+      });
+    }
+
+    return result as Record<WalletVersion, string>;
+  }
+}
+
+export class ReadOnlyWallet implements WalletProvider {
+  public address: Address;
+
+  constructor(address: string | Address) {
+    this.address =
+      typeof address === "string" ? Address.parse(address) : address;
+  }
+
+  async sendTransfer(): Promise<void> {
+    throw new Error("ReadOnlyWallet cannot sign transactions.");
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"]
+}