@unicitylabs/uniclaw 0.1.0

package/src/tools/get-transaction-history.ts

@@ -0,0 +1,42 @@
+/** Agent tool: uniclaw_get_transaction_history — view transaction history. */
+
+import { Type } from "@sinclair/typebox";
+import { getSphere } from "../sphere.js";
+import { getCoinDecimals, toHumanReadable } from "../assets.js";
+
+export const getTransactionHistoryTool = {
+  name: "uniclaw_get_transaction_history",
+  description:
+    "Get recent transaction history for the wallet. Returns the most recent transactions first.",
+  parameters: Type.Object({
+    limit: Type.Optional(Type.Number({ description: "Maximum number of entries to return (default 20)", minimum: 1 })),
+  }),
+  async execute(_toolCallId: string, params: { limit?: number }) {
+    const sphere = getSphere();
+    const history = sphere.payments.getHistory();
+    const sorted = [...history].sort((a, b) => b.timestamp - a.timestamp);
+    const limited = sorted.slice(0, params.limit ?? 20);
+
+    if (limited.length === 0) {
+      return {
+        content: [{ type: "text" as const, text: "No transaction history." }],
+      };
+    }
+
+    const lines = limited.map((e) => {
+      const time = new Date(e.timestamp).toISOString();
+      const decimals = getCoinDecimals(e.coinId) ?? 0;
+      const amount = toHumanReadable(e.amount, decimals);
+      const peer = e.type === "SENT" && e.recipientNametag
+        ? ` to @${e.recipientNametag}`
+        : e.type === "RECEIVED" && e.senderPubkey
+          ? ` from ${e.senderPubkey.slice(0, 12)}…`
+          : "";
+      return `[${time}] ${e.type} ${amount} ${e.symbol}${peer}`;
+    });
+
+    return {
+      content: [{ type: "text" as const, text: lines.join("\n") }],
+    };
+  },
+};

package/src/tools/list-payment-requests.ts

@@ -0,0 +1,82 @@
+/** Agent tool: uniclaw_list_payment_requests — view incoming/outgoing payment requests. */
+
+import { Type } from "@sinclair/typebox";
+import { getSphere } from "../sphere.js";
+import { getCoinDecimals, getCoinSymbol, toHumanReadable } from "../assets.js";
+
+export const listPaymentRequestsTool = {
+  name: "uniclaw_list_payment_requests",
+  description:
+    "List payment requests — incoming (others requesting payment from you), outgoing (your requests to others), or all.",
+  parameters: Type.Object({
+    direction: Type.Optional(
+      Type.Union([
+        Type.Literal("incoming"),
+        Type.Literal("outgoing"),
+        Type.Literal("all"),
+      ], { description: "Filter direction (default: all)" }),
+    ),
+    status: Type.Optional(
+      Type.Union([
+        Type.Literal("pending"),
+        Type.Literal("accepted"),
+        Type.Literal("rejected"),
+        Type.Literal("paid"),
+        Type.Literal("expired"),
+      ], { description: "Filter by status" }),
+    ),
+  }),
+  async execute(
+    _toolCallId: string,
+    params: {
+      direction?: "incoming" | "outgoing" | "all";
+      status?: "pending" | "accepted" | "rejected" | "paid" | "expired";
+    },
+  ) {
+    const sphere = getSphere();
+    const direction = params.direction ?? "all";
+    const statusFilter = params.status;
+    const sections: string[] = [];
+
+    if (direction === "incoming" || direction === "all") {
+      const incoming = sphere.payments.getPaymentRequests(
+        statusFilter ? { status: statusFilter } : undefined,
+      );
+      if (incoming.length > 0) {
+        const lines = incoming.map((r) => {
+          const from = r.senderNametag ? `@${r.senderNametag}` : r.senderPubkey.slice(0, 12) + "…";
+          const decimals = getCoinDecimals(r.coinId) ?? 0;
+          const amount = toHumanReadable(r.amount, decimals);
+          const msg = r.message ? ` — "${r.message}"` : "";
+          return `  ${r.requestId.slice(0, 12)}… | ${amount} ${r.symbol} from ${from} | ${r.status}${msg}`;
+        });
+        sections.push(`Incoming (${incoming.length}):\n${lines.join("\n")}`);
+      } else {
+        sections.push("Incoming: none");
+      }
+    }
+
+    if (direction === "outgoing" || direction === "all") {
+      const outgoing = sphere.payments.getOutgoingPaymentRequests(
+        statusFilter ? { status: statusFilter } : undefined,
+      );
+      if (outgoing.length > 0) {
+        const lines = outgoing.map((r) => {
+          const to = r.recipientNametag ? `@${r.recipientNametag}` : r.recipientPubkey.slice(0, 12) + "…";
+          const decimals = getCoinDecimals(r.coinId) ?? 0;
+          const amount = toHumanReadable(r.amount, decimals);
+          const symbol = getCoinSymbol(r.coinId);
+          const msg = r.message ? ` — "${r.message}"` : "";
+          return `  ${r.id.slice(0, 12)}… | ${amount} ${symbol} to ${to} | ${r.status}${msg}`;
+        });
+        sections.push(`Outgoing (${outgoing.length}):\n${lines.join("\n")}`);
+      } else {
+        sections.push("Outgoing: none");
+      }
+    }
+
+    return {
+      content: [{ type: "text" as const, text: sections.join("\n\n") }],
+    };
+  },
+};

package/src/tools/list-tokens.ts

@@ -0,0 +1,51 @@
+/** Agent tool: uniclaw_list_tokens — list individual tokens in the wallet. */
+
+import { Type } from "@sinclair/typebox";
+import { getSphere } from "../sphere.js";
+import { getCoinDecimals, toHumanReadable } from "../assets.js";
+
+export const listTokensTool = {
+  name: "uniclaw_list_tokens",
+  description:
+    "List individual tokens in the wallet, optionally filtered by coin ID and/or status.",
+  parameters: Type.Object({
+    coinId: Type.Optional(Type.String({ description: "Filter by coin ID (e.g. 'ALPHA')" })),
+    status: Type.Optional(
+      Type.Union([
+        Type.Literal("pending"),
+        Type.Literal("confirmed"),
+        Type.Literal("transferring"),
+        Type.Literal("spent"),
+        Type.Literal("invalid"),
+      ], { description: "Filter by token status" }),
+    ),
+  }),
+  async execute(
+    _toolCallId: string,
+    params: { coinId?: string; status?: "pending" | "confirmed" | "transferring" | "spent" | "invalid" },
+  ) {
+    const sphere = getSphere();
+    const tokens = sphere.payments.getTokens({
+      coinId: params.coinId,
+      status: params.status,
+    });
+
+    if (tokens.length === 0) {
+      return {
+        content: [{ type: "text" as const, text: "No tokens found matching the criteria." }],
+      };
+    }
+
+    const lines = tokens.map((t) => {
+      const decimals = getCoinDecimals(t.coinId) ?? 0;
+      const amount = toHumanReadable(t.amount, decimals);
+      return `${t.id.slice(0, 12)}… | ${amount} ${t.symbol} | ${t.status} | ${new Date(t.createdAt).toISOString()}`;
+    });
+
+    return {
+      content: [
+        { type: "text" as const, text: `Found ${tokens.length} token${tokens.length !== 1 ? "s" : ""}:\n${lines.join("\n")}` },
+      ],
+    };
+  },
+};

package/src/tools/request-payment.ts

@@ -0,0 +1,62 @@
+/** Agent tool: uniclaw_request_payment — request payment from someone. */
+
+import { Type } from "@sinclair/typebox";
+import { getSphere } from "../sphere.js";
+import { resolveCoinId, getCoinSymbol, getCoinDecimals, toSmallestUnit } from "../assets.js";
+import { validateRecipient } from "../validation.js";
+
+export const requestPaymentTool = {
+  name: "uniclaw_request_payment",
+  description:
+    "Send a payment request to another user, asking them to pay a specific amount.",
+  parameters: Type.Object({
+    recipient: Type.String({ description: "Nametag (e.g. @alice) or 64-char hex public key of who should pay" }),
+    amount: Type.Number({ description: "Amount to request (human-readable, e.g. 100 or 1.5)" }),
+    coin: Type.String({ description: "Coin to request by name or symbol (e.g. UCT, BTC)" }),
+    message: Type.Optional(Type.String({ description: "Optional message to include with the request" })),
+  }),
+  async execute(
+    _toolCallId: string,
+    params: { recipient: string; amount: number; coin: string; message?: string },
+  ) {
+    const recipient = params.recipient.trim();
+    validateRecipient(recipient);
+
+    if (params.amount <= 0) {
+      throw new Error("Amount must be greater than 0.");
+    }
+
+    const coinId = resolveCoinId(params.coin);
+    if (!coinId) {
+      throw new Error(`Unknown coin "${params.coin}".`);
+    }
+
+    const decimals = getCoinDecimals(coinId) ?? 0;
+    const amountSmallest = toSmallestUnit(params.amount, decimals);
+    const symbol = getCoinSymbol(coinId);
+
+    const sphere = getSphere();
+    const normalized = recipient.replace(/^@/, "");
+
+    const result = await sphere.payments.sendPaymentRequest(normalized, {
+      amount: amountSmallest,
+      coinId,
+      message: params.message,
+    });
+
+    if (!result.success) {
+      return {
+        content: [{ type: "text" as const, text: `Payment request failed: ${result.error ?? "unknown error"}` }],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Payment request sent to ${params.recipient} for ${params.amount} ${symbol} (request id: ${result.requestId})`,
+        },
+      ],
+    };
+  },
+};

package/src/tools/respond-payment-request.ts

@@ -0,0 +1,58 @@
+/** Agent tool: uniclaw_respond_payment_request — accept, reject, or pay a payment request. */
+
+import { Type } from "@sinclair/typebox";
+import { getSphere } from "../sphere.js";
+
+export const respondPaymentRequestTool = {
+  name: "uniclaw_respond_payment_request",
+  description:
+    "Respond to an incoming payment request by paying, accepting, or rejecting it. IMPORTANT: Only pay requests when explicitly instructed by the wallet owner.",
+  parameters: Type.Object({
+    requestId: Type.String({ description: "The payment request ID to respond to" }),
+    action: Type.Union([
+      Type.Literal("pay"),
+      Type.Literal("accept"),
+      Type.Literal("reject"),
+    ], { description: "Action to take: pay (send tokens immediately), accept (mark as accepted), or reject" }),
+    memo: Type.Optional(Type.String({ description: "Optional memo (used with 'pay' action)" })),
+  }),
+  async execute(
+    _toolCallId: string,
+    params: { requestId: string; action: string; memo?: string },
+  ) {
+    const sphere = getSphere();
+
+    switch (params.action) {
+      case "pay": {
+        const result = await sphere.payments.payPaymentRequest(params.requestId, params.memo);
+        if (result.error) {
+          return {
+            content: [{ type: "text" as const, text: `Payment failed: ${result.error}` }],
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: `Payment request ${params.requestId} paid — transfer ${result.id} (status: ${result.status})`,
+            },
+          ],
+        };
+      }
+      case "accept": {
+        await sphere.payments.acceptPaymentRequest(params.requestId);
+        return {
+          content: [{ type: "text" as const, text: `Payment request ${params.requestId} accepted.` }],
+        };
+      }
+      case "reject": {
+        await sphere.payments.rejectPaymentRequest(params.requestId);
+        return {
+          content: [{ type: "text" as const, text: `Payment request ${params.requestId} rejected.` }],
+        };
+      }
+      default:
+        throw new Error(`Invalid action: "${params.action}". Expected "pay", "accept", or "reject".`);
+    }
+  },
+};

package/src/tools/send-message.ts

@@ -0,0 +1,30 @@
+/** Agent tool: uniclaw_send_message — send a Nostr DM via Sphere. */
+
+import { Type } from "@sinclair/typebox";
+import { getSphere } from "../sphere.js";
+import { validateRecipient } from "../validation.js";
+
+export const sendMessageTool = {
+  name: "uniclaw_send_message",
+  description:
+    "Send a direct message to a Unicity/Nostr user. The recipient can be a nametag (e.g. @alice) or a hex public key.",
+  parameters: Type.Object({
+    recipient: Type.String({ description: "Nametag or public key of the recipient" }),
+    message: Type.String({ description: "Message text to send" }),
+  }),
+  async execute(_toolCallId: string, params: { recipient: string; message: string }) {
+    const recipient = params.recipient.trim();
+    validateRecipient(recipient);
+    const sphere = getSphere();
+    const normalized = recipient.replace(/^@/, "");
+    const dm = await sphere.communications.sendDM(normalized, params.message);
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Message sent to ${params.recipient} (id: ${dm.id})`,
+        },
+      ],
+    };
+  },
+};

package/src/tools/send-tokens.ts

@@ -0,0 +1,63 @@
+/** Agent tool: uniclaw_send_tokens — transfer tokens to a recipient. */
+
+import { Type } from "@sinclair/typebox";
+import { getSphere } from "../sphere.js";
+import { resolveCoinId, getCoinSymbol, getCoinDecimals, toSmallestUnit } from "../assets.js";
+import { validateRecipient } from "../validation.js";
+
+export const sendTokensTool = {
+  name: "uniclaw_send_tokens",
+  description:
+    "Send tokens to a recipient by nametag or public key. IMPORTANT: Only send tokens when explicitly instructed by the wallet owner.",
+  parameters: Type.Object({
+    recipient: Type.String({ description: "Nametag (e.g. @alice) or 64-char hex public key" }),
+    amount: Type.Number({ description: "Amount to send (human-readable, e.g. 100 or 1.5)" }),
+    coin: Type.String({ description: "Coin to send by name or symbol (e.g. UCT, BTC)" }),
+    memo: Type.Optional(Type.String({ description: "Optional memo to attach to the transfer" })),
+  }),
+  async execute(
+    _toolCallId: string,
+    params: { recipient: string; amount: number; coin: string; memo?: string },
+  ) {
+    const recipient = params.recipient.trim();
+    validateRecipient(recipient);
+
+    if (params.amount <= 0) {
+      throw new Error("Amount must be greater than 0.");
+    }
+
+    const coinId = resolveCoinId(params.coin);
+    if (!coinId) {
+      throw new Error(`Unknown coin "${params.coin}".`);
+    }
+
+    const decimals = getCoinDecimals(coinId) ?? 0;
+    const amountSmallest = toSmallestUnit(params.amount, decimals);
+    const symbol = getCoinSymbol(coinId);
+
+    const sphere = getSphere();
+    const normalized = recipient.replace(/^@/, "");
+
+    const result = await sphere.payments.send({
+      recipient: normalized,
+      amount: amountSmallest,
+      coinId,
+      memo: params.memo,
+    });
+
+    if (result.error) {
+      return {
+        content: [{ type: "text" as const, text: `Transfer failed: ${result.error}` }],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Transfer ${result.id} — ${params.amount} ${symbol} sent to ${params.recipient} (status: ${result.status})`,
+        },
+      ],
+    };
+  },
+};

package/src/tools/top-up.ts

@@ -0,0 +1,81 @@
+/** Agent tool: uniclaw_top_up — request test tokens from the faucet. */
+
+import { Type } from "@sinclair/typebox";
+import { getSphere } from "../sphere.js";
+import { resolveCoinId, getCoinSymbol, getAvailableSymbols } from "../assets.js";
+
+const FAUCET_API_URL = process.env.UNICLAW_FAUCET_URL
+  ?? "https://faucet.unicity.network/api/v1/faucet/request";
+
+export const topUpTool = {
+  name: "uniclaw_top_up",
+  description:
+    "Request test tokens from the Unicity faucet. This is for testnet only.",
+  parameters: Type.Object({
+    coin: Type.String({ description: "Coin to request by name or symbol (e.g. UCT, BTC, SOL)" }),
+    amount: Type.Number({ description: "Amount to request (can be decimal)" }),
+  }),
+  async execute(_toolCallId: string, params: { coin: string; amount: number }) {
+    const sphere = getSphere();
+    const nametag = sphere.identity?.nametag;
+
+    if (!nametag) {
+      throw new Error("Wallet has no nametag. A nametag is required to receive tokens from the faucet.");
+    }
+
+    const coinId = resolveCoinId(params.coin);
+    if (!coinId) {
+      const validCoins = getAvailableSymbols().join(", ");
+      throw new Error(`Unknown coin "${params.coin}". Available coins: ${validCoins}`);
+    }
+
+    if (params.amount <= 0) {
+      throw new Error("Amount must be greater than 0.");
+    }
+
+    const response = await fetch(FAUCET_API_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        unicityId: nametag.replace(/^@/, ""),
+        coin: coinId,
+        amount: params.amount,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Faucet request failed: ${response.status} ${response.statusText} — ${errorText}`,
+          },
+        ],
+      };
+    }
+
+    const data = await response.json();
+    const displaySymbol = getCoinSymbol(coinId);
+
+    if (data.success === false) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Faucet request failed: ${data.message ?? "unknown error"}`,
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Faucet request successful: ${params.amount} ${displaySymbol} sent to @${nametag.replace(/^@/, "")}. Tokens should arrive shortly.`,
+        },
+      ],
+    };
+  },
+};

package/src/validation.ts

@@ -0,0 +1,15 @@
+/** Shared validation constants and helpers. */
+
+/** Nametag: starts with a letter, alphanumeric + hyphens/underscores, max 32 chars. */
+export const NAMETAG_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]{0,31}$/;
+
+/** Valid recipient: nametag (with optional @) or 64-char hex public key. */
+export const VALID_RECIPIENT = /^@?\w[\w-]{0,31}$|^[0-9a-fA-F]{64}$/;
+
+export function validateRecipient(recipient: string): void {
+  if (!VALID_RECIPIENT.test(recipient.trim())) {
+    throw new Error(
+      `Invalid recipient format: "${recipient}". Expected a nametag or 64-char hex public key.`,
+    );
+  }
+}