@railbeam/stardorm-api-contract 0.0.1 → 0.0.2

package/src/chat-api.ts

@@ -1,6 +1,24 @@
 import { z } from "zod";
 import { handlerActionIdSchema } from "./handlers.js";
 
+/**
+ * Recursively convert JSON `null` to `undefined` so optional Zod fields accept
+ * model output and Mongo payloads (`intro: null` otherwise fails chat parse).
+ */
+export function stripJsonNulls(value: unknown): unknown {
+  if (value === null) return undefined;
+  if (Array.isArray(value)) return value.map(stripJsonNulls);
+  if (typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      const stripped = stripJsonNulls(v);
+      if (stripped !== undefined) out[k] = stripped;
+    }
+    return out;
+  }
+  return value;
+}
+
 export const stardormChatRichRowSchema = z.object({
   label: z.string(),
   value: z.string(),
@@ -80,6 +98,56 @@ export const stardormChatRichBlockSchema = z.discriminatedUnion("type", [
     title: z.string().min(1),
     rows: stardormChatRichRows,
   }),
+  z.object({
+    type: z.literal("swap_checkout_form"),
+    title: z.string().min(1).max(200),
+    intro: z.string().max(2000).optional(),
+    supportedAssets: z.array(x402SupportedAssetSchema).min(1).max(24),
+    networks: z
+      .array(
+        z.object({
+          id: z.string().min(1).max(64),
+          label: z.string().min(1).max(120),
+        }),
+      )
+      .max(16)
+      .optional(),
+    /** Default V3 fee tier when the form does not override (500, 3000, 10000). */
+    defaultPoolFee: z.union([z.literal(500), z.literal(3000), z.literal(10000)]).optional(),
+  }),
+  z.object({
+    type: z.literal("marketplace_hire"),
+    title: z.string().min(1).max(200),
+    intro: z.string().max(2000).optional(),
+    specialistName: z.string().min(1).max(80),
+    specialistAgentKey: z.string().min(1).max(64),
+    category: z
+      .enum(["Payments", "Taxes", "Reports", "DeFi", "Compliance", "General"])
+      .optional(),
+    capability: z.string().min(1).max(400).optional(),
+    userTask: z.string().max(500).optional(),
+    /** App path to open the marketplace (default `/marketplace`). */
+    marketplacePath: z.string().min(1).max(256).default("/marketplace"),
+    /** App path to the specialist profile when known (e.g. `/agents/chain-2`). */
+    agentProfilePath: z.string().min(1).max(256).optional(),
+    requiredHandler: z.string().min(1).max(64).optional(),
+  }),
+  z.object({
+    type: z.literal("transfer_checkout_form"),
+    title: z.string().min(1).max(200),
+    intro: z.string().max(2000).optional(),
+    supportedAssets: z.array(x402SupportedAssetSchema).min(1).max(24),
+    networks: z
+      .array(
+        z.object({
+          id: z.string().min(1).max(64),
+          label: z.string().min(1).max(120),
+        }),
+      )
+      .max(16)
+      .optional(),
+    defaultTo: z.string().max(66).optional(),
+  }),
 ]);
 
 export type StardormChatRichBlock = z.infer<typeof stardormChatRichBlockSchema>;
@@ -114,18 +182,30 @@ export const stardormChatAttachmentSchema = z.object({
 
 export type StardormChatAttachment = z.infer<typeof stardormChatAttachmentSchema>;
 
-export const stardormChatSuccessSchema = z.object({
+/** JSON APIs sometimes emit `null` for omitted optional fields. */
+function nullishOptional<T extends z.ZodTypeAny>(schema: T) {
+  return z.preprocess((v) => (v === null ? undefined : v), schema);
+}
+
+const stardormChatSuccessObjectSchema = z.object({
   agentKey: z.string().min(1),
   reply: z.string(),
-  structured: stardormChatStructuredSchema.optional(),
+  structured: nullishOptional(stardormChatStructuredSchema.optional()),
   /** Structured card rows for the client (model or server-generated). */
-  rich: stardormChatRichBlockSchema.optional(),
+  rich: nullishOptional(stardormChatRichBlockSchema.optional()),
   /** Files the server uploaded to 0G Storage from the user's chat turn (echoed for immediate render). */
-  attachments: z.array(stardormChatAttachmentSchema).optional(),
+  attachments: nullishOptional(
+    z.array(stardormChatAttachmentSchema).optional(),
+  ),
   compute: stardormChatComputeSchema,
 });
 
-export type StardormChatSuccess = z.infer<typeof stardormChatSuccessSchema>;
+export const stardormChatSuccessSchema = z.preprocess(
+  (v) => (v != null && typeof v === "object" ? stripJsonNulls(v) : v),
+  stardormChatSuccessObjectSchema,
+);
+
+export type StardormChatSuccess = z.infer<typeof stardormChatSuccessObjectSchema>;
 
 export const stardormChatClientErrorSchema = z.object({
   error: z.string().min(1),

package/src/conversation-sync.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { chatHistoryMessageSchema } from "./conversation.js";
+
+/** Lightweight invalidation hint (legacy clients refetch the thread). */
+export const conversationSyncThreadSchema = z.object({
+  v: z.literal(1),
+  op: z.literal("thread"),
+  conversationId: z.string().min(1),
+});
+
+/** Full message rows for in-place TanStack cache updates (no refetch). */
+export const conversationSyncThreadMessagesSchema = z.object({
+  v: z.literal(1),
+  op: z.literal("thread_messages"),
+  conversationId: z.string().min(1),
+  messages: z.array(chatHistoryMessageSchema).min(1),
+});
+
+export const conversationSyncConversationsSchema = z.object({
+  v: z.literal(1),
+  op: z.literal("conversations"),
+});
+
+export const conversationSyncConversationDeletedSchema = z.object({
+  v: z.literal(1),
+  op: z.literal("conversation_deleted"),
+  conversationId: z.string().min(1),
+});
+
+export const conversationSyncPayloadSchema = z.discriminatedUnion("op", [
+  conversationSyncThreadSchema,
+  conversationSyncThreadMessagesSchema,
+  conversationSyncConversationsSchema,
+  conversationSyncConversationDeletedSchema,
+]);
+
+export type ConversationSyncThreadPayload = z.infer<typeof conversationSyncThreadSchema>;
+export type ConversationSyncThreadMessagesPayload = z.infer<
+  typeof conversationSyncThreadMessagesSchema
+>;
+export type ConversationSyncPayload = z.infer<typeof conversationSyncPayloadSchema>;

package/src/conversation.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { handlerActionIdSchema } from "./handlers.js";
-import { stardormChatRichBlockSchema } from "./chat-api.js";
+import { stripJsonNulls, stardormChatRichBlockSchema } from "./chat-api.js";
+import { chatHandlerResultSchema } from "./handler-result.js";
 
 export const chatHistoryQuerySchema = z.object({
   limit: z.coerce.number().int().min(1).max(100).default(40),
@@ -66,8 +67,15 @@ export const chatHistoryMessageSchema = z.object({
   content: z.string(),
   createdAt: z.number(),
   attachments: z.array(chatHistoryAttachmentSchema).optional(),
-  rich: stardormChatRichBlockSchema.optional(),
+  rich: z
+    .preprocess(
+      (v) => (v != null && typeof v === "object" ? stripJsonNulls(v) : v),
+      stardormChatRichBlockSchema.optional(),
+    )
+    .optional(),
   handlerCta: chatHistoryHandlerCtaSchema.optional(),
+  /** Wallet or server outcome for this bubble (tx hash, checkout ids, …). */
+  result: chatHandlerResultSchema.optional(),
   followUp: chatFollowUpSchema.optional(),
   model: z.string().optional(),
   verified: z.boolean().optional(),

package/src/credit-card.ts

@@ -90,28 +90,6 @@ export const creditCardsListResponseSchema = z.object({
 
 export type CreditCardsListResponse = z.infer<typeof creditCardsListResponseSchema>;
 
-export const creditCardFundBodySchema = z
-  .object({
-    amountCents: z.coerce.number().int().min(1).max(100_000_000),
-    fundingTxHash: z
-      .string()
-      .regex(/^0x[a-fA-F0-9]{64}$/)
-      .optional(),
-    fundingChainId: z.coerce.number().int().positive().optional(),
-  })
-  .refine(
-    (d) =>
-      (d.fundingTxHash == null && d.fundingChainId == null) ||
-      (d.fundingTxHash != null && d.fundingChainId != null),
-    {
-      message:
-        "fundingTxHash and fundingChainId must both be provided or both omitted",
-      path: ["fundingTxHash"],
-    },
-  );
-
-export type CreditCardFundBody = z.infer<typeof creditCardFundBodySchema>;
-
 export const creditCardFundQuoteQuerySchema = z.object({
   amountCents: z.coerce.number().int().min(1).max(100_000_000),
 });
@@ -120,11 +98,18 @@ export type CreditCardFundQuoteQuery = z.infer<
   typeof creditCardFundQuoteQuerySchema
 >;
 
-export const creditCardFundQuoteOffChainSchema = z.object({
+/** USDC.e x402 fund on 0G mainnet (1 USD cent = 10_000 base units). */
+export const creditCardFundQuoteX402Schema = z.object({
   onchainFundingRequired: z.literal(false),
+  chainId: z.number().int(),
+  recipient: z.string().min(1),
+  usdcAsset: z.string().min(1),
+  usdcAmountBaseUnits: z.string().regex(/^\d+$/),
+  usdcDecimals: z.number().int().min(0).max(18),
 });
 
-export const creditCardFundQuoteOnChainSchema = z.object({
+/** Native 0G transfer to treasury (used when x402 is not configured). */
+export const creditCardFundQuoteNativeSchema = z.object({
   onchainFundingRequired: z.literal(true),
   chainId: z.number().int(),
   recipient: z.string().min(1),
@@ -134,14 +119,20 @@ export const creditCardFundQuoteOnChainSchema = z.object({
   nativeDecimals: z.number().int().min(0).max(18),
 });
 
-export const creditCardFundQuoteResponseSchema = z.discriminatedUnion(
+export const creditCardFundQuoteSchema = z.discriminatedUnion(
   "onchainFundingRequired",
-  [creditCardFundQuoteOffChainSchema, creditCardFundQuoteOnChainSchema],
+  [creditCardFundQuoteX402Schema, creditCardFundQuoteNativeSchema],
 );
 
-export type CreditCardFundQuoteResponse = z.infer<
-  typeof creditCardFundQuoteResponseSchema
->;
+export type CreditCardFundQuote = z.infer<typeof creditCardFundQuoteSchema>;
+export type CreditCardFundQuoteX402 = z.infer<typeof creditCardFundQuoteX402Schema>;
+export type CreditCardFundQuoteNative = z.infer<typeof creditCardFundQuoteNativeSchema>;
+
+/** @deprecated Use {@link CreditCardFundQuote} */
+export type CreditCardFundQuoteResponse = CreditCardFundQuote;
+
+/** @deprecated Use {@link creditCardFundQuoteSchema} */
+export const creditCardFundQuoteResponseSchema = creditCardFundQuoteSchema;
 
 export const creditCardWithdrawBodySchema = z.object({
   amountCents: z.coerce.number().int().min(1).max(100_000_000),

package/src/financial-snapshot.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+/** One UTC daily rollup row (Mongo `FinancialSnapshot` → chat / dashboard). */
+export const financialSnapshotDailyRowSchema = z.object({
+  bucketStart: z.string(),
+  bucket: z.string(),
+  revenueUsd: z.number().optional(),
+  walletBalance0g: z.number().optional(),
+  monthlySpend0g: z.number().optional(),
+  spendByCategory: z.record(z.number()).default({}),
+});
+
+export type FinancialSnapshotDailyRow = z.infer<typeof financialSnapshotDailyRowSchema>;
+
+/** Query for GET `/users/me/financial-snapshots`. */
+export const meFinancialSnapshotsQuerySchema = z.object({
+  days: z.coerce.number().int().min(7).max(90).default(30),
+});
+
+export type MeFinancialSnapshotsQuery = z.infer<typeof meFinancialSnapshotsQuerySchema>;
+
+export const financialSnapshotsListResponseSchema = z.object({
+  items: z.array(financialSnapshotDailyRowSchema),
+});
+
+export type FinancialSnapshotsListResponse = z.infer<
+  typeof financialSnapshotsListResponseSchema
+>;

package/src/handler-result.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+/** Outcome after a wallet-signed handler CTA (transfer, swap, …). */
+export const chatHandlerWalletTxResultSchema = z.object({
+  kind: z.literal("wallet_tx"),
+  status: z.enum(["submitted", "confirmed", "failed"]),
+  txHash: z
+    .string()
+    .regex(/^0x[a-fA-F0-9]{64}$/)
+    .optional(),
+  error: z.string().max(2000).optional(),
+  network: z.string().min(1).max(64).optional(),
+  chainId: z.number().int().positive().optional(),
+  handler: z.string().min(1).max(64).optional(),
+  updatedAt: z.number().int().positive(),
+});
+
+export type ChatHandlerWalletTxResult = z.infer<typeof chatHandlerWalletTxResultSchema>;
+
+/** Outcome after `execute-handler` (server job, checkout created, draft recorded, …). */
+export const chatHandlerServerResultSchema = z.object({
+  kind: z.literal("server"),
+  status: z.enum(["completed", "failed"]).default("completed"),
+  data: z.record(z.string(), z.unknown()).optional(),
+  updatedAt: z.number().int().positive(),
+});
+
+export type ChatHandlerServerResult = z.infer<typeof chatHandlerServerResultSchema>;
+
+export const chatHandlerResultSchema = z.discriminatedUnion("kind", [
+  chatHandlerWalletTxResultSchema,
+  chatHandlerServerResultSchema,
+]);
+
+export type ChatHandlerResult = z.infer<typeof chatHandlerResultSchema>;
+
+export const patchChatMessageResultBodySchema = z.object({
+  result: chatHandlerResultSchema,
+});
+
+export type PatchChatMessageResultBody = z.infer<typeof patchChatMessageResultBodySchema>;
+
+export const patchChatMessageResultResponseSchema = z.object({
+  ok: z.literal(true),
+  messageId: z.string().min(1),
+  result: chatHandlerResultSchema,
+  rich: z
+    .object({
+      type: z.literal("tx"),
+      title: z.string(),
+      rows: z
+        .array(
+          z.object({
+            label: z.string(),
+            value: z.string(),
+          }),
+        )
+        .optional(),
+    })
+    .optional(),
+});
+
+export type PatchChatMessageResultResponse = z.infer<
+  typeof patchChatMessageResultResponseSchema
+>;

package/src/handlers.ts

@@ -23,6 +23,10 @@ export const HANDLER_ACTION_IDS = [
   "draft_erc20_transfer",
   /** Confirms an NFT (ERC-721 / ERC-1155) transfer draft; user signs in their wallet / Beam Send. */
   "draft_nft_transfer",
+  /** Confirms a Uniswap V3 single-hop swap on 0G mainnet; user signs approve + router in wallet. */
+  "draft_token_swap",
+  /** Direct the user to hire a marketplace specialist for a task this agent cannot run. */
+  "suggest_marketplace_hire",
 ] as const;
 
 export type HandlerActionId = (typeof HANDLER_ACTION_IDS)[number];

package/src/index.ts

@@ -60,6 +60,7 @@ export {
   stardormChatStructuredSchema,
   stardormChatComputeSchema,
   stardormChatRichRowSchema,
+  stripJsonNulls,
   stardormChatRichBlockSchema,
   x402SupportedAssetSchema,
   stardormChatSuccessSchema,
@@ -98,6 +99,16 @@ export {
   type CreateConversationBody,
   type DeleteConversationResponse,
 } from "./conversation.js";
+export {
+  conversationSyncPayloadSchema,
+  conversationSyncThreadSchema,
+  conversationSyncThreadMessagesSchema,
+  conversationSyncConversationsSchema,
+  conversationSyncConversationDeletedSchema,
+  type ConversationSyncPayload,
+  type ConversationSyncThreadPayload,
+  type ConversationSyncThreadMessagesPayload,
+} from "./conversation-sync.js";
 export {
   agentOnchainFeedbackItemSchema,
   agentFeedbacksQuerySchema,
@@ -118,6 +129,14 @@ export {
   type MePaymentRequestsQuery,
   type PaymentRequestsListResponse,
 } from "./payment-request.js";
+export {
+  financialSnapshotDailyRowSchema,
+  meFinancialSnapshotsQuerySchema,
+  financialSnapshotsListResponseSchema,
+  type FinancialSnapshotDailyRow,
+  type MeFinancialSnapshotsQuery,
+  type FinancialSnapshotsListResponse,
+} from "./financial-snapshot.js";
 export {
   onRampFormCtaParamsSchema,
   onRampFormNetworkOptionSchema,
@@ -149,10 +168,10 @@ export {
   creditCardPublicSchema,
   creditCardSensitiveDetailsSchema,
   creditCardsListResponseSchema,
-  creditCardFundBodySchema,
   creditCardFundQuoteQuerySchema,
-  creditCardFundQuoteOffChainSchema,
-  creditCardFundQuoteOnChainSchema,
+  creditCardFundQuoteSchema,
+  creditCardFundQuoteX402Schema,
+  creditCardFundQuoteNativeSchema,
   creditCardFundQuoteResponseSchema,
   creditCardWithdrawBodySchema,
   type CreateCreditCardInput,
@@ -160,7 +179,9 @@ export {
   type CreditCardPublic,
   type CreditCardSensitiveDetails,
   type CreditCardsListResponse,
-  type CreditCardFundBody,
+  type CreditCardFundQuote,
+  type CreditCardFundQuoteX402,
+  type CreditCardFundQuoteNative,
   type CreditCardFundQuoteQuery,
   type CreditCardFundQuoteResponse,
   type CreditCardWithdrawBody,
@@ -190,3 +211,34 @@ export {
   type DraftErc20TransferInput,
   type DraftNftTransferInput,
 } from "./transfer-drafts.js";
+export {
+  swapFormCtaParamsSchema,
+  swapFormNetworkOptionSchema,
+  draftTokenSwapInputSchema,
+  isSwapFormCtaParams,
+  type SwapFormCtaParams,
+  type DraftTokenSwapInput,
+} from "./swap.js";
+export {
+  transferFormCtaParamsSchema,
+  transferFormNetworkOptionSchema,
+  isTransferFormCtaParams,
+  type TransferFormCtaParams,
+} from "./transfer-form.js";
+export {
+  suggestMarketplaceHireInputSchema,
+  marketplaceSpecialistAgentKeySchema,
+  type SuggestMarketplaceHireInput,
+} from "./marketplace-hire.js";
+export {
+  chatHandlerResultSchema,
+  chatHandlerWalletTxResultSchema,
+  chatHandlerServerResultSchema,
+  patchChatMessageResultBodySchema,
+  patchChatMessageResultResponseSchema,
+  type ChatHandlerResult,
+  type ChatHandlerWalletTxResult,
+  type ChatHandlerServerResult,
+  type PatchChatMessageResultBody,
+  type PatchChatMessageResultResponse,
+} from "./handler-result.js";

package/src/marketplace-hire.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { handlerActionIdSchema } from "./handlers.js";
+
+/** Known Beam catalog specialist keys (subgraph / marketplace). */
+export const marketplaceSpecialistAgentKeySchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9][a-z0-9-]*$/i);
+
+export const suggestMarketplaceHireInputSchema = z.object({
+  specialistAgentKey: marketplaceSpecialistAgentKeySchema,
+  specialistName: z.string().min(1).max(80).optional(),
+  category: z
+    .enum(["Payments", "Taxes", "Reports", "DeFi", "Compliance", "General"])
+    .optional(),
+  /** One line: what the specialist runs for the user (handler names ok). */
+  capability: z.string().min(1).max(400).optional(),
+  /** Short description of what the user was trying to do. */
+  userTask: z.string().min(1).max(500).optional(),
+  intro: z.string().max(2000).optional(),
+  /** Optional handler the user needs after hiring (for display only). */
+  requiredHandler: handlerActionIdSchema.optional(),
+});
+
+export type SuggestMarketplaceHireInput = z.infer<typeof suggestMarketplaceHireInputSchema>;

package/src/payment-request.ts

@@ -67,6 +67,8 @@ export const publicPaymentRequestSchema = z.object({
   /** Set when status is `paid` (on-chain settlement recorded). */
   txHash: z.string().optional(),
   paidByWallet: z.string().optional(),
+  /** When true, checkout can settle via x402 facilitator + wallet-signed payload. */
+  facilitatorSettlement: z.boolean().optional(),
 });
 
 export type PublicPaymentRequest = z.infer<typeof publicPaymentRequestSchema>;
@@ -74,12 +76,16 @@ export type PublicPaymentRequest = z.infer<typeof publicPaymentRequestSchema>;
 /** Query for GET `/users/me/payment-requests`. */
 export const mePaymentRequestsQuerySchema = z.object({
   limit: z.coerce.number().int().min(1).max(50).default(20),
+  /** 1-based page index (sorted by `updatedAt` descending). */
+  page: z.coerce.number().int().min(1).default(1),
 });
 
 export type MePaymentRequestsQuery = z.infer<typeof mePaymentRequestsQuerySchema>;
 
 export const paymentRequestsListResponseSchema = z.object({
   items: z.array(publicPaymentRequestSchema),
+  /** Total rows matching the wallet filter (ignores pagination). */
+  total: z.number().int().min(0),
 });
 
 export type PaymentRequestsListResponse = z.infer<

package/src/swap.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { x402SupportedAssetSchema } from "./chat-api.js";
+
+export const swapFormNetworkOptionSchema = z.object({
+  id: z.string().min(1).max(64),
+  label: z.string().min(1).max(120),
+});
+
+/** Persisted on the chat CTA row until the user submits the swap form. */
+export const swapFormCtaParamsSchema = z.object({
+  _swapForm: z.literal(true),
+  supportedAssets: z.array(x402SupportedAssetSchema).min(1).max(24),
+  networks: z.array(swapFormNetworkOptionSchema).max(16).optional(),
+  intro: z.string().max(2000).optional(),
+  /** Default Uniswap V3 pool fee tier (500, 3000, or 10000). */
+  defaultPoolFee: z.union([z.literal(500), z.literal(3000), z.literal(10000)]).optional(),
+});
+
+export type SwapFormCtaParams = z.infer<typeof swapFormCtaParamsSchema>;
+
+export function isSwapFormCtaParams(v: unknown): v is SwapFormCtaParams {
+  return swapFormCtaParamsSchema.safeParse(v).success;
+}
+
+const caip2Eip155 = z
+  .string()
+  .min(8)
+  .max(64)
+  .regex(/^eip155:\d+$/, "network must be CAIP-2 form eip155:<chainId>");
+
+const evmAddress20 = z
+  .string()
+  .trim()
+  .refine((s) => /^0x[a-fA-F0-9]{40}$/.test(s), "must be a 0x-prefixed 20-byte EVM address")
+  .transform((s) => s.trim().toLowerCase());
+
+const positiveWeiString = z
+  .string()
+  .trim()
+  .regex(/^[1-9]\d*$/, "must be a positive integer decimal string (base units)");
+
+const nonNegativeWeiString = z
+  .string()
+  .trim()
+  .regex(/^\d+$/, "must be a non-negative integer decimal string (base units)");
+
+const poolFeeSchema = z.union([
+  z.literal(500),
+  z.literal(3000),
+  z.literal(10000),
+]);
+
+/** Confirmed swap draft — user signs approve (if needed) + router `exactInputSingle` in wallet. */
+export const draftTokenSwapInputSchema = z.object({
+  network: caip2Eip155,
+  tokenIn: evmAddress20,
+  tokenInSymbol: z.string().min(1).max(32).optional(),
+  tokenInDecimals: z.number().int().min(0).max(36),
+  tokenOut: evmAddress20,
+  tokenOutSymbol: z.string().min(1).max(32).optional(),
+  tokenOutDecimals: z.number().int().min(0).max(36),
+  amountInWei: positiveWeiString,
+  /** Slippage floor in `tokenOut` base units; `0` accepts any output. */
+  amountOutMinimumWei: nonNegativeWeiString.default("0"),
+  poolFee: poolFeeSchema.default(3000),
+  /** Filled server-side from deployment when omitted. */
+  router: evmAddress20.optional(),
+  /** Unix seconds; wallet may refresh if expired. */
+  deadlineUnix: z.number().int().positive().optional(),
+  note: z.string().max(500).optional(),
+});
+
+export type DraftTokenSwapInput = z.infer<typeof draftTokenSwapInputSchema>;

package/src/transfer-form.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { x402SupportedAssetSchema } from "./chat-api.js";
+
+export const transferFormNetworkOptionSchema = z.object({
+  id: z.string().min(1).max(64),
+  label: z.string().min(1).max(120),
+});
+
+/** Persisted on the chat CTA row until the user submits the transfer form. */
+export const transferFormCtaParamsSchema = z.object({
+  _transferForm: z.literal(true),
+  supportedAssets: z.array(x402SupportedAssetSchema).min(1).max(24),
+  networks: z.array(transferFormNetworkOptionSchema).max(16).optional(),
+  intro: z.string().max(2000).optional(),
+  /** When set, pre-fill recipient in the form. */
+  defaultTo: z
+    .string()
+    .trim()
+    .refine((s) => /^0x[a-fA-F0-9]{40}$/.test(s), "defaultTo must be 0x…40")
+    .transform((s) => s.toLowerCase())
+    .optional(),
+});
+
+export type TransferFormCtaParams = z.infer<typeof transferFormCtaParamsSchema>;
+
+export function isTransferFormCtaParams(v: unknown): v is TransferFormCtaParams {
+  return transferFormCtaParamsSchema.safeParse(v).success;
+}