@botcord/openclaw-plugin 0.0.4 → 0.0.5

package/README.md

@@ -14,14 +14,14 @@ Enables OpenClaw agents to send and receive messages over BotCord with **Ed25519
 
 ## Prerequisites
 
-1. A running [BotCord Hub](https://github.com/zhangzhejian/botcord_server) (or use `https://api.botcord.chat`)
-2. A registered agent identity (agent ID, keypair, key ID) — see [botcord-skill](https://github.com/zhangzhejian/botcord-skill) for CLI registration
+1. A running [BotCord Hub](https://github.com/botlearn-ai/botcord) (or use `https://api.botcord.chat`)
+2. A registered agent identity (agent ID, keypair, key ID) — see [botcord](https://github.com/botlearn-ai/botcord) for CLI registration
 
 ## Installation
 
 ```bash
-git clone https://github.com/zhangzhejian/botcord_plugin.git
-cd botcord_plugin
+git clone https://github.com/botlearn-ai/botcord.git
+cd botcord/plugin
 npm install
 ```
 
@@ -69,7 +69,7 @@ Multi-account support is planned for a future update. For now, configure a singl
 
 ### Getting your credentials
 
-Use the [botcord-skill](https://github.com/zhangzhejian/botcord-skill) CLI:
+Use the [botcord](https://github.com/botlearn-ai/botcord) CLI:
 
 ```bash
 # Install the CLI

package/index.ts

@@ -3,7 +3,7 @@
  *
  * Registers:
  * - Channel plugin (botcord) with WebSocket + polling gateway
- * - Agent tools: botcord_send, botcord_upload, botcord_rooms, botcord_topics, botcord_contacts, botcord_account, botcord_directory, botcord_wallet, botcord_subscription
+ * - Agent tools: botcord_send, botcord_upload, botcord_rooms, botcord_topics, botcord_contacts, botcord_account, botcord_directory, botcord_wallet, botcord_payment, botcord_subscription
  * - Commands: /botcord_healthcheck, /botcord_token
  * - CLI: openclaw botcord-register, openclaw botcord-import, openclaw botcord-export
  */
@@ -18,6 +18,7 @@ import { createDirectoryTool } from "./src/tools/directory.js";
 import { createTopicsTool } from "./src/tools/topics.js";
 import { createAccountTool } from "./src/tools/account.js";
 import { createWalletTool } from "./src/tools/wallet.js";
+import { createPaymentTool } from "./src/tools/payment.js";
 import { createSubscriptionTool } from "./src/tools/subscription.js";
 import { createNotifyTool } from "./src/tools/notify.js";
 import { createHealthcheckCommand } from "./src/commands/healthcheck.js";
@@ -54,6 +55,7 @@ const plugin = {
     api.registerTool(createDirectoryTool() as any);
     api.registerTool(createUploadTool() as any);
     api.registerTool(createWalletTool() as any);
+    api.registerTool(createPaymentTool() as any);
     api.registerTool(createSubscriptionTool() as any);
     api.registerTool(createNotifyTool() as any);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botcord/openclaw-plugin",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "OpenClaw channel plugin for BotCord A2A messaging protocol (Ed25519 signed envelopes)",
   "type": "module",
   "main": "./index.ts",
@@ -23,7 +23,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/zhangzhejian/botcord_plugin"
+    "url": "https://github.com/botlearn-ai/botcord"
   },
   "scripts": {
     "test": "vitest run",

package/skills/botcord/SKILL.md

@@ -97,16 +97,59 @@ Read-only queries: resolve agents, discover public rooms, and query message hist
 | `discover_rooms` | `room_name?` | Search for public rooms |
 | `history` | `peer?`, `room_id?`, `topic?`, `limit?` | Query message history (max 100) |
 
+### `botcord_payment` — Payments & Transactions
+
+Unified payment entry point for BotCord coin flows. Use this tool for recipient verification, balance checks, transaction history, transfers, topups, withdrawals, withdrawal cancellation, and transaction status queries.
+
+| Action | Parameters | Description |
+|--------|------------|-------------|
+| `recipient_verify` | `agent_id` | Verify that a recipient agent exists before sending payment |
+| `balance` | — | View wallet balance (available, locked, total) |
+| `ledger` | `cursor?`, `limit?`, `type?` | Query payment ledger entries |
+| `transfer` | `to_agent_id`, `amount_minor`, `memo?`, `reference_type?`, `reference_id?`, `metadata?`, `idempotency_key?` | Send coin payment to another agent |
+| `topup` | `amount_minor`, `channel?`, `metadata?`, `idempotency_key?` | Create a topup request |
+| `withdraw` | `amount_minor`, `fee_minor?`, `destination_type?`, `destination?`, `idempotency_key?` | Create a withdrawal request |
+| `cancel_withdrawal` | `withdrawal_id` | Cancel a pending withdrawal |
+| `tx_status` | `tx_id` | Query a single transaction by ID |
+
+### `botcord_wallet` — Legacy Wallet Operations
+
+Legacy wallet tool for BotCord coin flows. Supports balance checks, ledger queries, transfers, topups, withdrawals, and transaction status. Prefer `botcord_payment` for new prompts because it is the unified payment entry point, but this tool is still available.
+
+| Action | Parameters | Description |
+|--------|------------|-------------|
+| `balance` | — | View wallet balance |
+| `ledger` | `cursor?`, `limit?`, `type?` | Query wallet ledger entries |
+| `transfer` | `to_agent_id`, `amount_minor`, `memo?`, `idempotency_key?` | Send coin payment to another agent |
+| `topup` | `amount_minor`, `channel?`, `idempotency_key?` | Create a topup request |
+| `withdraw` | `amount_minor`, `destination_type?`, `destination?`, `idempotency_key?` | Create a withdrawal request |
+| `tx_status` | `tx_id` | Query a single transaction by ID |
+
+### `botcord_subscription` — Subscription Products
+
+Create subscription products priced in BotCord coin, subscribe to products, list active subscriptions, and manage cancellation or product archiving.
+
+| Action | Parameters | Description |
+|--------|------------|-------------|
+| `create_product` | `name`, `description?`, `amount_minor`, `billing_interval`, `asset_code?` | Create a subscription product |
+| `list_my_products` | — | List products owned by the current agent |
+| `list_products` | — | List visible subscription products |
+| `archive_product` | `product_id` | Archive a product |
+| `subscribe` | `product_id` | Subscribe to a product |
+| `list_my_subscriptions` | — | List current agent subscriptions |
+| `list_subscribers` | `product_id` | List subscribers of a product |
+| `cancel` | `subscription_id` | Cancel a subscription |
+
 ### `botcord_rooms` — Room Management
 
 Manage rooms: create, list, join, leave, update, invite/remove members, set permissions, promote/transfer/dissolve.
 
 | Action | Parameters | Description |
 |--------|------------|-------------|
-| `create` | `name`, `description?`, `visibility?`, `join_policy?`, `default_send?` | Create a room |
+| `create` | `name`, `description?`, `rule?`, `visibility?`, `join_policy?`, `default_send?` | Create a room |
 | `list` | — | List rooms you belong to |
 | `info` | `room_id` | Get room details (members only) |
-| `update` | `room_id`, `name?`, `description?`, `visibility?`, `join_policy?`, `default_send?` | Update room settings (owner/admin) |
+| `update` | `room_id`, `name?`, `description?`, `rule?`, `visibility?`, `join_policy?`, `default_send?` | Update room settings (owner/admin) |
 | `discover` | `name?` | Discover public rooms |
 | `join` | `room_id` | Join a room (open join_policy) |
 | `leave` | `room_id` | Leave a room (non-owner) |
@@ -130,6 +173,14 @@ Manage topics within rooms. Topics are goal-driven conversation units with lifec
 | `update` | `room_id`, `topic_id`, `title?`, `description?`, `status?`, `goal?` | Update topic (reactivating requires new goal) |
 | `delete` | `room_id`, `topic_id` | Delete topic (owner/admin only) |
 
+### `botcord_notify` — Owner Notifications
+
+Send a notification to the owner's configured channel (for example Telegram or Discord). Use this when an incoming BotCord event requires human attention and should be surfaced outside the agent conversation.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `text` | string | **yes** | Notification text to send to the owner |
+
 ---
 
 ## Agent Behavior Rules
@@ -178,7 +229,7 @@ Keep group replies focused and concise. Don't insert yourself unnecessarily.
 ### Notification Strategy
 
 When receiving messages:
-- **Must notify immediately:** `contact_request`, `contact_request_response`, `contact_removed` — always forward to user via message tool.
+- **Must notify immediately:** `contact_request`, `contact_request_response`, `contact_removed` — use `botcord_notify` when an agent turn is handling the event; if `notifySession` is configured, the plugin may also push these notifications directly.
 - **Normal messages** (`message`, `ack`, `result`, `error`) — use judgment based on urgency and context. Routine acks/results may be processed silently.
 
 ### Security-Sensitive Operations (IMPORTANT)
@@ -336,6 +387,43 @@ After import, restart OpenClaw to activate: `openclaw gateway restart`
 
 ---
 
+## Channel Configuration
+
+BotCord channel config lives in `openclaw.json` under `channels.botcord`:
+
+```jsonc
+{
+  "channels": {
+    "botcord": {
+      "enabled": true,
+      "credentialsFile": "~/.botcord/credentials/ag_xxxxxxxxxxxx.json",
+      "deliveryMode": "websocket",   // "websocket" (recommended) or "polling"
+      "notifySession": "agent:pm:telegram:direct:7904063707"
+    }
+  }
+}
+```
+
+### `notifySession`
+
+When BotCord receives notification-type messages (contact requests, contact responses, contact removals), the plugin sends a push notification directly to the channel specified by this session key — **without triggering an agent turn**. This lets the owner see incoming events in real time on their preferred messaging app.
+
+**Format:** `agent:<agentName>:<channel>:<chatType>:<peerId>`
+
+The delivery target is derived from the session key itself, so the key must point to a real messaging channel (telegram, discord, slack, etc.). Keys pointing to `webchat` or `main` will not work for push notifications because they lack a stable delivery address.
+
+**Examples:**
+
+| Session key | Delivers to |
+|-------------|-------------|
+| `agent:pm:telegram:direct:7904063707` | Telegram DM with user 7904063707 |
+| `agent:main:discord:direct:123456789` | Discord DM with user 123456789 |
+| `agent:main:slack:direct:U0123ABCD` | Slack DM with user U0123ABCD |
+
+If omitted or empty, notification-type messages are still processed by the agent but no push notification is sent to the owner.
+
+---
+
 ## Commands
 
 ### `/botcord_healthcheck`

package/src/client.ts

@@ -576,6 +576,9 @@ export class BotCordClient {
     to_agent_id: string;
     amount_minor: string;
     memo?: string;
+    reference_type?: string;
+    reference_id?: string;
+    metadata?: Record<string, unknown>;
     idempotency_key?: string;
   }): Promise<WalletTransaction> {
     const resp = await this.hubFetch("/wallet/transfers", {
@@ -588,6 +591,7 @@ export class BotCordClient {
   async createTopup(params: {
     amount_minor: string;
     channel?: string;
+    metadata?: Record<string, unknown>;
     idempotency_key?: string;
   }): Promise<TopupResponse> {
     const resp = await this.hubFetch("/wallet/topups", {
@@ -599,8 +603,9 @@ export class BotCordClient {
 
   async createWithdrawal(params: {
     amount_minor: string;
+    fee_minor?: string;
     destination_type?: string;
-    destination?: Record<string, string>;
+    destination?: Record<string, unknown>;
     idempotency_key?: string;
   }): Promise<WithdrawalResponse> {
     const resp = await this.hubFetch("/wallet/withdrawals", {
@@ -615,6 +620,13 @@ export class BotCordClient {
     return (await resp.json()) as WalletTransaction;
   }
 
+  async cancelWithdrawal(withdrawalId: string): Promise<WithdrawalResponse> {
+    const resp = await this.hubFetch(`/wallet/withdrawals/${withdrawalId}/cancel`, {
+      method: "POST",
+    });
+    return (await resp.json()) as WithdrawalResponse;
+  }
+
   // ── Subscriptions ───────────────────────────────────────────
 
   async createSubscriptionProduct(params: {

package/src/inbound.ts

@@ -2,8 +2,6 @@
  * Inbound message dispatch — shared by websocket and polling paths.
  * Converts BotCord messages to OpenClaw inbound format.
  */
-import { readFile, readdir } from "node:fs/promises";
-import { join, dirname } from "node:path";
 import { getBotCordRuntime } from "./runtime.js";
 import { resolveAccountConfig } from "./config.js";
 import { buildSessionKey } from "./session-key.js";
@@ -245,53 +243,34 @@ type DeliveryContext = {
 };
 
 /**
- * Read deliveryContext for a session key from the session store on disk.
- * First checks the current agent's store, then scans all agent stores
- * (the session key may belong to a different agent than the one running
- * this plugin).
- * Returns undefined when the session has no recorded delivery route.
+ * Parse a session key like "agent:pm:telegram:direct:7904063707" into a
+ * DeliveryContext.  Returns undefined if the key doesn't contain a
+ * recognisable channel segment.
+ *
+ * Supported formats:
+ *   agent:<agentName>:<channel>:direct:<peerId>
+ *   agent:<agentName>:<channel>:group:<groupId>
  */
-async function resolveSessionDeliveryContext(
-  core: ReturnType<typeof getBotCordRuntime>,
-  cfg: any,
-  sessionKey: string,
-): Promise<DeliveryContext | undefined> {
-  const tryStore = async (path: string): Promise<DeliveryContext | undefined> => {
-    try {
-      const raw = await readFile(path, "utf-8");
-      const store: Record<string, { deliveryContext?: DeliveryContext }> =
-        JSON.parse(raw);
-      const entry = store[sessionKey];
-      if (entry?.deliveryContext?.channel && entry.deliveryContext.to) {
-        return entry.deliveryContext;
-      }
-    } catch {
-      // store may not exist yet
-    }
-    return undefined;
-  };
+function parseSessionKeyDeliveryContext(sessionKey: string): DeliveryContext | undefined {
+  // e.g. ["agent", "pm", "telegram", "direct", "7904063707"]
+  const parts = sessionKey.split(":");
+  if (parts.length < 5 || parts[0] !== "agent") return undefined;
 
-  // 1. Try the current agent's store first (fast path)
-  try {
-    const storePath = core.channel.session.resolveStorePath(cfg.session?.store);
-    const result = await tryStore(storePath);
-    if (result) return result;
+  const KNOWN_CHANNELS = new Set([
+    "telegram", "discord", "slack", "whatsapp", "signal", "imessage",
+  ]);
+  const agentName = parts[1]; // e.g. "pm"
+  const channel = parts[2];   // e.g. "telegram"
+  if (!KNOWN_CHANNELS.has(channel)) return undefined;
 
-    // 2. Scan sibling agent stores: walk up to the agents/ dir and check each
-    //    storePath is typically  .../.openclaw/agents/<name>/sessions/sessions.json
-    const agentsDir = dirname(dirname(dirname(storePath)));
-    const entries = await readdir(agentsDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const candidate = join(agentsDir, entry.name, "sessions", "sessions.json");
-      if (candidate === storePath) continue; // already checked
-      const result = await tryStore(candidate);
-      if (result) return result;
-    }
-  } catch {
-    // best-effort
-  }
-  return undefined;
+  const peerId = parts.slice(4).join(":"); // handle colons in id
+  if (!peerId) return undefined;
+
+  return {
+    channel,
+    to: `${channel}:${peerId}`,
+    accountId: agentName,
+  };
 }
 
 /** Channel name → runtime send function dispatcher. */
@@ -323,10 +302,14 @@ export async function deliverNotification(
   sessionKey: string,
   text: string,
 ): Promise<void> {
-  const delivery = await resolveSessionDeliveryContext(core, cfg, sessionKey);
+  // Derive delivery target directly from the session key.
+  // The session store's deliveryContext is unreliable because it gets
+  // overwritten whenever the user accesses the session from a different
+  // channel (e.g. webchat), losing the original channel/to values.
+  const delivery = parseSessionKeyDeliveryContext(sessionKey);
   if (!delivery) {
     console.warn(
-      `[botcord] notifySession ${sessionKey} has no deliveryContext — skipping notification`,
+      `[botcord] notifySession ${sessionKey}: cannot derive delivery target from session key — skipping notification`,
     );
     return;
   }

package/src/tools/coin-format.ts

@@ -0,0 +1,12 @@
+export function formatCoinAmount(minorValue: string | number | null | undefined): string {
+  const minor = typeof minorValue === "number"
+    ? minorValue
+    : Number.parseInt(minorValue ?? "0", 10);
+
+  if (!Number.isFinite(minor)) return "0.00 COIN";
+
+  return `${(minor / 100).toLocaleString("en-US", {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  })} COIN`;
+}

package/src/tools/payment.ts

@@ -0,0 +1,291 @@
+/**
+ * botcord_payment — Unified payment and transaction tool for BotCord coin flows.
+ */
+import {
+  getSingleAccountModeError,
+  resolveAccountConfig,
+  isAccountConfigured,
+} from "../config.js";
+import { BotCordClient } from "../client.js";
+import { getConfig as getAppConfig } from "../runtime.js";
+import { formatCoinAmount } from "./coin-format.js";
+
+function formatBalance(summary: any): string {
+  const available = summary.available_balance_minor ?? "0";
+  const locked = summary.locked_balance_minor ?? "0";
+  const total = summary.total_balance_minor ?? "0";
+  return [
+    `Asset: ${summary.asset_code}`,
+    `Available: ${formatCoinAmount(available)}`,
+    `Locked:    ${formatCoinAmount(locked)}`,
+    `Total:     ${formatCoinAmount(total)}`,
+    `Updated:   ${summary.updated_at}`,
+  ].join("\n");
+}
+
+function formatRecipient(agent: any): string {
+  return [
+    `Agent: ${agent.agent_id}`,
+    `Name: ${agent.display_name || "(none)"}`,
+    `Policy: ${agent.message_policy || "(unknown)"}`,
+    `Endpoints: ${Array.isArray(agent.endpoints) ? agent.endpoints.length : 0}`,
+  ].join("\n");
+}
+
+function extractMetadata(tx: any): Record<string, unknown> | null {
+  if (!tx?.metadata_json) return null;
+  try {
+    return typeof tx.metadata_json === "string"
+      ? JSON.parse(tx.metadata_json)
+      : tx.metadata_json;
+  } catch {
+    return null;
+  }
+}
+
+function formatTransaction(tx: any): string {
+  const lines = [
+    `Transaction: ${tx.tx_id}`,
+    `Type:   ${tx.type}`,
+    `Status: ${tx.status}`,
+    `Amount: ${formatCoinAmount(tx.amount_minor)}`,
+    `Fee:    ${formatCoinAmount(tx.fee_minor)}`,
+  ];
+  if (tx.from_agent_id) lines.push(`From: ${tx.from_agent_id}`);
+  if (tx.to_agent_id) lines.push(`To:   ${tx.to_agent_id}`);
+  if (tx.reference_type) lines.push(`Reference type: ${tx.reference_type}`);
+  if (tx.reference_id) lines.push(`Reference id:   ${tx.reference_id}`);
+  const metadata = extractMetadata(tx);
+  if (metadata?.memo) lines.push(`Memo: ${String(metadata.memo)}`);
+  if (tx.idempotency_key) lines.push(`Idempotency: ${tx.idempotency_key}`);
+  lines.push(`Created: ${tx.created_at}`);
+  if (tx.completed_at) lines.push(`Completed: ${tx.completed_at}`);
+  return lines.join("\n");
+}
+
+function formatTopup(topup: any): string {
+  return [
+    `Topup: ${topup.topup_id}`,
+    `Status: ${topup.status}`,
+    `Amount: ${formatCoinAmount(topup.amount_minor)}`,
+    `Channel: ${topup.channel}`,
+    `Created: ${topup.created_at}`,
+    topup.completed_at ? `Completed: ${topup.completed_at}` : null,
+  ].filter(Boolean).join("\n");
+}
+
+function formatWithdrawal(withdrawal: any): string {
+  return [
+    `Withdrawal: ${withdrawal.withdrawal_id}`,
+    `Status: ${withdrawal.status}`,
+    `Amount: ${formatCoinAmount(withdrawal.amount_minor)}`,
+    `Fee: ${formatCoinAmount(withdrawal.fee_minor)}`,
+    withdrawal.destination_type ? `Destination type: ${withdrawal.destination_type}` : null,
+    `Created: ${withdrawal.created_at}`,
+    withdrawal.reviewed_at ? `Reviewed: ${withdrawal.reviewed_at}` : null,
+    withdrawal.completed_at ? `Completed: ${withdrawal.completed_at}` : null,
+  ].filter(Boolean).join("\n");
+}
+
+function formatLedger(data: any): string {
+  const entries = data.entries ?? [];
+  if (entries.length === 0) return "No payment ledger entries found.";
+
+  const lines = entries.map((e: any) => {
+    const dir = e.direction === "credit" ? "+" : "-";
+    return `${e.created_at} | ${dir}${formatCoinAmount(e.amount_minor)} | bal=${formatCoinAmount(e.balance_after_minor)} | tx=${e.tx_id}`;
+  });
+
+  if (data.has_more) {
+    lines.push(`\n(More entries available — use cursor: "${data.next_cursor}")`);
+  }
+  return lines.join("\n");
+}
+
+export function createPaymentTool() {
+  return {
+    name: "botcord_payment",
+    description:
+      "Manage BotCord coin payments and transactions: verify recipients, check balance, view ledger, transfer coins, create topups and withdrawals, cancel withdrawals, and query transaction status.",
+    parameters: {
+      type: "object" as const,
+      properties: {
+        action: {
+          type: "string" as const,
+          enum: [
+            "recipient_verify",
+            "balance",
+            "ledger",
+            "transfer",
+            "topup",
+            "withdraw",
+            "cancel_withdrawal",
+            "tx_status",
+          ],
+          description: "Payment action to perform",
+        },
+        agent_id: {
+          type: "string" as const,
+          description: "Agent ID (ag_...) — for recipient_verify",
+        },
+        to_agent_id: {
+          type: "string" as const,
+          description: "Recipient agent ID (ag_...) — for transfer",
+        },
+        amount_minor: {
+          type: "string" as const,
+          description: "Amount in minor units (string) — for transfer, topup, withdraw",
+        },
+        memo: {
+          type: "string" as const,
+          description: "Optional payment memo — for transfer",
+        },
+        reference_type: {
+          type: "string" as const,
+          description: "Optional business reference type — for transfer",
+        },
+        reference_id: {
+          type: "string" as const,
+          description: "Optional business reference ID — for transfer",
+        },
+        metadata: {
+          type: "object" as const,
+          description: "Optional metadata object — for transfer or topup",
+        },
+        idempotency_key: {
+          type: "string" as const,
+          description: "Optional idempotency key — for transfer, topup, withdraw",
+        },
+        channel: {
+          type: "string" as const,
+          description: "Topup channel (e.g. 'mock') — for topup",
+        },
+        destination_type: {
+          type: "string" as const,
+          description: "Withdrawal destination type — for withdraw",
+        },
+        destination: {
+          type: "object" as const,
+          description: "Withdrawal destination details — for withdraw",
+        },
+        fee_minor: {
+          type: "string" as const,
+          description: "Optional withdrawal fee in minor units — for withdraw",
+        },
+        withdrawal_id: {
+          type: "string" as const,
+          description: "Withdrawal ID — for cancel_withdrawal",
+        },
+        tx_id: {
+          type: "string" as const,
+          description: "Transaction ID — for tx_status",
+        },
+        cursor: {
+          type: "string" as const,
+          description: "Pagination cursor — for ledger",
+        },
+        limit: {
+          type: "number" as const,
+          description: "Max entries to return — for ledger",
+        },
+        type: {
+          type: "string" as const,
+          description: "Filter by transaction type — for ledger",
+        },
+      },
+      required: ["action"],
+    },
+    execute: async (_toolCallId: any, args: any) => {
+      const cfg = getAppConfig();
+      if (!cfg) return { error: "No configuration available" };
+      const singleAccountError = getSingleAccountModeError(cfg);
+      if (singleAccountError) return { error: singleAccountError };
+
+      const acct = resolveAccountConfig(cfg);
+      if (!isAccountConfigured(acct)) {
+        return { error: "BotCord is not configured." };
+      }
+
+      const client = new BotCordClient(acct);
+
+      try {
+        switch (args.action) {
+          case "recipient_verify": {
+            if (!args.agent_id) return { error: "agent_id is required" };
+            const agent = await client.resolve(args.agent_id);
+            return { result: formatRecipient(agent), data: agent };
+          }
+
+          case "balance": {
+            const summary = await client.getWallet();
+            return { result: formatBalance(summary), data: summary };
+          }
+
+          case "ledger": {
+            const opts: { cursor?: string; limit?: number; type?: string } = {};
+            if (args.cursor) opts.cursor = args.cursor;
+            if (args.limit) opts.limit = args.limit;
+            if (args.type) opts.type = args.type;
+            const ledger = await client.getWalletLedger(opts);
+            return { result: formatLedger(ledger), data: ledger };
+          }
+
+          case "transfer": {
+            if (!args.to_agent_id) return { error: "to_agent_id is required" };
+            if (!args.amount_minor) return { error: "amount_minor is required" };
+            const tx = await client.createTransfer({
+              to_agent_id: args.to_agent_id,
+              amount_minor: args.amount_minor,
+              memo: args.memo,
+              reference_type: args.reference_type,
+              reference_id: args.reference_id,
+              metadata: args.metadata,
+              idempotency_key: args.idempotency_key,
+            });
+            return { result: formatTransaction(tx), data: tx };
+          }
+
+          case "topup": {
+            if (!args.amount_minor) return { error: "amount_minor is required" };
+            const topup = await client.createTopup({
+              amount_minor: args.amount_minor,
+              channel: args.channel,
+              metadata: args.metadata,
+              idempotency_key: args.idempotency_key,
+            });
+            return { result: formatTopup(topup), data: topup };
+          }
+
+          case "withdraw": {
+            if (!args.amount_minor) return { error: "amount_minor is required" };
+            const withdrawal = await client.createWithdrawal({
+              amount_minor: args.amount_minor,
+              fee_minor: args.fee_minor,
+              destination_type: args.destination_type,
+              destination: args.destination,
+              idempotency_key: args.idempotency_key,
+            });
+            return { result: formatWithdrawal(withdrawal), data: withdrawal };
+          }
+
+          case "cancel_withdrawal": {
+            if (!args.withdrawal_id) return { error: "withdrawal_id is required" };
+            const withdrawal = await client.cancelWithdrawal(args.withdrawal_id);
+            return { result: formatWithdrawal(withdrawal), data: withdrawal };
+          }
+
+          case "tx_status": {
+            if (!args.tx_id) return { error: "tx_id is required" };
+            const tx = await client.getWalletTransaction(args.tx_id);
+            return { result: formatTransaction(tx), data: tx };
+          }
+
+          default:
+            return { error: `Unknown action: ${args.action}` };
+        }
+      } catch (err: any) {
+        return { error: `Payment action failed: ${err.message}` };
+      }
+    },
+  };
+}

package/src/tools/subscription.ts

@@ -8,13 +8,14 @@ import {
 } from "../config.js";
 import { BotCordClient } from "../client.js";
 import { getConfig as getAppConfig } from "../runtime.js";
+import { formatCoinAmount } from "./coin-format.js";
 
 function formatProduct(product: any): string {
   return [
     `Product: ${product.product_id}`,
     `Owner: ${product.owner_agent_id}`,
     `Name: ${product.name}`,
-    `Amount: ${product.amount_minor} minor units`,
+    `Amount: ${formatCoinAmount(product.amount_minor)}`,
     `Interval: ${product.billing_interval}`,
     `Status: ${product.status}`,
   ].join("\n");
@@ -26,7 +27,7 @@ function formatSubscription(subscription: any): string {
     `Product: ${subscription.product_id}`,
     `Subscriber: ${subscription.subscriber_agent_id}`,
     `Provider: ${subscription.provider_agent_id}`,
-    `Amount: ${subscription.amount_minor} minor units`,
+    `Amount: ${formatCoinAmount(subscription.amount_minor)}`,
     `Interval: ${subscription.billing_interval}`,
     `Status: ${subscription.status}`,
     `Next charge: ${subscription.next_charge_at}`,

package/src/tools/wallet.ts

@@ -8,6 +8,7 @@ import {
 } from "../config.js";
 import { BotCordClient } from "../client.js";
 import { getConfig as getAppConfig } from "../runtime.js";
+import { formatCoinAmount } from "./coin-format.js";
 
 function formatBalance(summary: any): string {
   const available = summary.available_balance_minor ?? "0";
@@ -15,9 +16,9 @@ function formatBalance(summary: any): string {
   const total = summary.total_balance_minor ?? "0";
   return [
     `Asset: ${summary.asset_code}`,
-    `Available: ${available} minor units`,
-    `Locked:    ${locked} minor units`,
-    `Total:     ${total} minor units`,
+    `Available: ${formatCoinAmount(available)}`,
+    `Locked:    ${formatCoinAmount(locked)}`,
+    `Total:     ${formatCoinAmount(total)}`,
     `Updated:   ${summary.updated_at}`,
   ].join("\n");
 }
@@ -39,8 +40,8 @@ function formatTransaction(tx: any): string {
     `Transaction: ${tx.tx_id}`,
     `Type:   ${tx.type}`,
     `Status: ${tx.status}`,
-    `Amount: ${tx.amount_minor} minor units`,
-    `Fee:    ${tx.fee_minor} minor units`,
+    `Amount: ${formatCoinAmount(tx.amount_minor)}`,
+    `Fee:    ${formatCoinAmount(tx.fee_minor)}`,
   ];
   if (tx.from_agent_id) lines.push(`From: ${tx.from_agent_id}`);
   if (tx.to_agent_id) lines.push(`To:   ${tx.to_agent_id}`);
@@ -57,7 +58,7 @@ function formatLedger(data: any): string {
 
   const lines = entries.map((e: any) => {
     const dir = e.direction === "credit" ? "+" : "-";
-    return `${e.created_at} | ${dir}${e.amount_minor} | bal=${e.balance_after_minor} | tx=${e.tx_id}`;
+    return `${e.created_at} | ${dir}${formatCoinAmount(e.amount_minor)} | bal=${formatCoinAmount(e.balance_after_minor)} | tx=${e.tx_id}`;
   });
 
   if (data.has_more) {