@agentpay-ai/shared 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@agentpay-ai/shared",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/account-admin.ts",
+    "src/approval.ts",
+    "src/balance.ts",
+    "src/chains.ts",
+    "src/index.ts",
+    "src/invoice.ts",
+    "src/payment-intent.ts",
+    "src/payment-tracking.ts",
+    "src/tokens.ts",
+    "src/wallet-setup.ts",
+    "src/x402.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "tsx --test \"src/**/*.test.ts\"",
+    "typecheck": "tsc -p ../../tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.2.0",
+    "zod": "^4.4.3"
+  }
+}

package/src/account-admin.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+
+import { evmAddressSchema } from "./payment-intent.ts";
+
+const positiveIntegerStringSchema = z.string().regex(/^[1-9]\d*$/, "Expected a positive integer string");
+
+export const prepareAccountAdminTransactionInputSchema = z.discriminatedUnion("action", [
+  z.object({
+    action: z.literal("PAUSE"),
+  }),
+  z.object({
+    action: z.literal("UNPAUSE"),
+  }),
+  z.object({
+    action: z.literal("SET_EXECUTOR"),
+    newExecutorAddress: evmAddressSchema,
+  }),
+  z.object({
+    action: z.literal("CANCEL_NONCE"),
+    nonce: positiveIntegerStringSchema,
+  }),
+  z.object({
+    action: z.literal("SET_ALLOWED_TOKEN"),
+    tokenAddress: evmAddressSchema,
+    allowed: z.boolean(),
+  }),
+  z.object({
+    action: z.literal("WITHDRAW_NATIVE"),
+    toAddress: evmAddressSchema,
+    amountAtomic: positiveIntegerStringSchema,
+  }),
+  z.object({
+    action: z.literal("WITHDRAW_TOKEN"),
+    tokenAddress: evmAddressSchema,
+    toAddress: evmAddressSchema,
+    amountAtomic: positiveIntegerStringSchema,
+  }),
+]);
+
+export type PrepareAccountAdminTransactionInput = z.infer<typeof prepareAccountAdminTransactionInputSchema>;

package/src/approval.ts

@@ -0,0 +1,7 @@
+export function createApprovalPhrase(paymentIntentId: string): string {
+  return `APPROVE ${paymentIntentId}`;
+}
+
+export function createApprovalInstruction(paymentIntentId: string): string {
+  return `To approve, reply exactly:\n${createApprovalPhrase(paymentIntentId)}`;
+}

package/src/balance.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+import { STABLE_TOKEN_SYMBOLS, stableTokenSymbolSchema } from "./tokens.ts";
+
+export const getBalanceInputSchema = z.object({
+  tokenSymbols: z.array(stableTokenSymbolSchema).min(1).default([...STABLE_TOKEN_SYMBOLS]),
+});
+
+export type GetBalanceInput = z.input<typeof getBalanceInputSchema>;
+export type ParsedGetBalanceInput = z.output<typeof getBalanceInputSchema>;

package/src/chains.ts

@@ -0,0 +1,55 @@
+export const SUPPORTED_CHAINS = {
+  56: {
+    id: 56,
+    name: "BNB Chain",
+    nativeCurrency: {
+      symbol: "BNB",
+      decimals: 18,
+    },
+  },
+  97: {
+    id: 97,
+    name: "BNB Chain Testnet",
+    nativeCurrency: {
+      symbol: "tBNB",
+      decimals: 18,
+    },
+  },
+  8453: {
+    id: 8453,
+    name: "Base",
+    nativeCurrency: {
+      symbol: "ETH",
+      decimals: 18,
+    },
+  },
+} as const;
+
+export type SupportedChainId = keyof typeof SUPPORTED_CHAINS;
+export type NativeCurrency = (typeof SUPPORTED_CHAINS)[SupportedChainId]["nativeCurrency"];
+
+export function getChainName(chainId: number): string {
+  return SUPPORTED_CHAINS[chainId as SupportedChainId]?.name ?? `Chain ${chainId}`;
+}
+
+export function getNativeCurrency(chainId: number): NativeCurrency {
+  const nativeCurrency = SUPPORTED_CHAINS[chainId as SupportedChainId]?.nativeCurrency;
+
+  if (!nativeCurrency) {
+    throw new Error(`Unsupported chain ${chainId}.`);
+  }
+
+  return nativeCurrency;
+}
+
+export function formatNativeAmount(atomicAmount: string, chainId: number): string {
+  const nativeCurrency = getNativeCurrency(chainId);
+  return `${atomicToDecimal(BigInt(atomicAmount), nativeCurrency.decimals)} ${nativeCurrency.symbol}`;
+}
+
+function atomicToDecimal(amount: bigint, decimals: number): string {
+  const padded = amount.toString().padStart(decimals + 1, "0");
+  const whole = padded.slice(0, -decimals);
+  const fractional = padded.slice(-decimals).replace(/0+$/, "");
+  return fractional ? `${whole}.${fractional}` : whole;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from "./approval.ts";
+export * from "./account-admin.ts";
+export * from "./balance.ts";
+export * from "./chains.ts";
+export * from "./invoice.ts";
+export * from "./payment-intent.ts";
+export * from "./payment-tracking.ts";
+export * from "./tokens.ts";
+export * from "./wallet-setup.ts";
+export * from "./x402.ts";

package/src/invoice.ts

@@ -0,0 +1,144 @@
+import { z } from "zod";
+
+import { getChainName } from "./chains.ts";
+import { preparePaymentInputSchema } from "./payment-intent.ts";
+import { stableTokenSymbolSchema } from "./tokens.ts";
+
+export const parseInvoicePaymentInputSchema = z.object({
+  invoice: z.string().trim().min(1),
+  sourceTokenSymbol: stableTokenSymbolSchema.default("USDT"),
+});
+
+export type ParseInvoicePaymentInput = z.input<typeof parseInvoicePaymentInputSchema>;
+
+export interface ParsedInvoicePayment {
+  invoiceId?: string;
+  recipientAddress: string;
+  destinationChainId: number;
+  destinationChain: string;
+  destinationTokenSymbol: "USDC" | "USDT";
+  amountOut: string;
+  purpose: string;
+  sourceTokenSymbol: "USDC" | "USDT";
+  paymentType: "INVOICE_PAYMENT";
+}
+
+export function parseInvoicePayment(rawInput: ParseInvoicePaymentInput): ParsedInvoicePayment {
+  const input = parseInvoicePaymentInputSchema.parse(rawInput);
+  const invoice = parseInvoiceFields(input.invoice);
+  const invoiceId = readField(invoice, ["invoiceid", "id", "invoice"]);
+  const purpose = readField(invoice, ["purpose", "memo", "description", "note"]) ?? invoicePurpose(invoiceId);
+  const candidate = {
+    recipientAddress: readField(invoice, ["recipientaddress", "recipient", "to", "payto"]),
+    destinationChainId: parseDestinationChainId(
+      readField(invoice, ["destinationchainid", "destinationchain", "chainid", "chain"]),
+    ),
+    destinationTokenSymbol: parseToken(readField(invoice, ["destinationtokensymbol", "token", "currency"])),
+    amountOut: readField(invoice, ["amountout", "amount", "amountdue", "total"]),
+    purpose,
+    sourceTokenSymbol: parseToken(readField(invoice, ["sourcetokensymbol", "sourcetoken"]) ?? input.sourceTokenSymbol),
+  };
+
+  const parsed = parsePaymentFields(candidate);
+
+  return {
+    invoiceId,
+    recipientAddress: parsed.recipientAddress,
+    destinationChainId: parsed.destinationChainId,
+    destinationChain: getChainName(parsed.destinationChainId),
+    destinationTokenSymbol: parsed.destinationTokenSymbol,
+    amountOut: parsed.amountOut,
+    purpose: parsed.purpose,
+    sourceTokenSymbol: parsed.sourceTokenSymbol,
+    paymentType: "INVOICE_PAYMENT",
+  };
+}
+
+function parseInvoiceFields(invoice: string): Record<string, unknown> {
+  const trimmed = invoice.trim();
+
+  if (trimmed.startsWith("{")) {
+    const parsed = JSON.parse(trimmed) as unknown;
+
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("Invalid invoice: expected a JSON object.");
+    }
+
+    return Object.fromEntries(
+      Object.entries(parsed as Record<string, unknown>).map(([key, value]) => [normalizeKey(key), value]),
+    );
+  }
+
+  return Object.fromEntries(
+    trimmed
+      .split(/\r?\n|;/)
+      .map((line) => line.match(/^\s*([^:=]+)\s*[:=]\s*(.+?)\s*$/))
+      .filter((match): match is RegExpMatchArray => Boolean(match))
+      .map((match) => [normalizeKey(match[1]), match[2].trim()]),
+  );
+}
+
+function readField(fields: Record<string, unknown>, aliases: string[]): string | undefined {
+  for (const alias of aliases) {
+    const value = fields[alias];
+
+    if (value !== undefined && value !== null && String(value).trim() !== "") {
+      return String(value).trim();
+    }
+  }
+
+  return undefined;
+}
+
+function parseDestinationChainId(value: string | undefined): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  if (/^\d+$/.test(value)) {
+    return Number(value);
+  }
+
+  const normalized = normalizeKey(value);
+  const knownChains: Record<string, number> = {
+    base: 8453,
+    bnbchain: 56,
+    bnb: 56,
+    bsc: 56,
+  };
+
+  return knownChains[normalized];
+}
+
+function parseToken(value: string | undefined): "USDC" | "USDT" | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  return stableTokenSymbolSchema.parse(value.trim().toUpperCase());
+}
+
+function parsePaymentFields(candidate: {
+  recipientAddress: string | undefined;
+  destinationChainId: number | undefined;
+  destinationTokenSymbol: "USDC" | "USDT" | undefined;
+  amountOut: string | undefined;
+  purpose: string | undefined;
+  sourceTokenSymbol: "USDC" | "USDT" | undefined;
+}) {
+  const parsed = preparePaymentInputSchema.safeParse(candidate);
+
+  if (!parsed.success) {
+    throw new Error(`Invalid invoice payment fields: ${parsed.error.issues.map((issue) => issue.path.join(".")).join(", ")}`);
+  }
+
+  return parsed.data;
+}
+
+function invoicePurpose(invoiceId: string | undefined): string | undefined {
+  return invoiceId ? `Invoice ${invoiceId}` : undefined;
+}
+
+function normalizeKey(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}

package/src/payment-intent.ts

@@ -0,0 +1,171 @@
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+import { z } from "zod";
+
+import { getChainName } from "./chains.ts";
+import { getStableTokenMetadata, stableTokenSymbolSchema } from "./tokens.ts";
+
+const addressPattern = /^0x[a-fA-F0-9]{40}$/;
+const hexPattern = /^0x(?:[a-fA-F0-9]{2})*$/;
+const positiveDecimalPattern = /^(?:0|[1-9]\d*)(?:\.\d+)?$/;
+
+export const evmAddressSchema = z.string().regex(addressPattern, "Expected an EVM address");
+
+export const hexDataSchema = z.string().regex(hexPattern, "Expected 0x-prefixed even-length hex data");
+
+export const positiveDecimalStringSchema = z.string().refine(
+  (value) => positiveDecimalPattern.test(value) && Number(value) > 0,
+  "Expected a positive decimal string",
+);
+
+export const paymentIntentStatusSchema = z.enum([
+  "AWAITING_APPROVAL",
+  "APPROVED",
+  "EXECUTING",
+  "COMPLETED",
+  "FAILED",
+  "EXPIRED",
+  "CANCELLED",
+]);
+
+export type PaymentIntentStatus = z.infer<typeof paymentIntentStatusSchema>;
+
+export const paymentTypeSchema = z.enum(["WALLET_PAYMENT", "INVOICE_PAYMENT", "X402_PAYMENT", "CONTRACT_CALL"]);
+
+export type PaymentType = z.infer<typeof paymentTypeSchema>;
+
+export const stablecoinPaymentTypeSchema = z.enum(["WALLET_PAYMENT", "INVOICE_PAYMENT", "X402_PAYMENT"]);
+
+export type StablecoinPaymentType = z.infer<typeof stablecoinPaymentTypeSchema>;
+
+export const preparePaymentInputSchema = z.object({
+  recipientAddress: evmAddressSchema,
+  destinationChainId: z.number().int().positive(),
+  destinationTokenSymbol: stableTokenSymbolSchema,
+  amountOut: positiveDecimalStringSchema,
+  purpose: z.string().trim().min(1).max(280),
+  sourceTokenSymbol: stableTokenSymbolSchema.default("USDT"),
+  paymentType: stablecoinPaymentTypeSchema.default("WALLET_PAYMENT"),
+});
+
+export const quotePaymentRouteInputSchema = preparePaymentInputSchema.omit({ purpose: true, paymentType: true });
+
+export type QuotePaymentRouteInput = z.input<typeof quotePaymentRouteInputSchema>;
+export type ParsedQuotePaymentRouteInput = z.output<typeof quotePaymentRouteInputSchema>;
+
+export type PreparePaymentInput = z.input<typeof preparePaymentInputSchema>;
+export type ParsedPreparePaymentInput = z.output<typeof preparePaymentInputSchema>;
+
+export const executePaymentInputSchema = z.object({
+  paymentIntentId: z.string().trim().min(1),
+  approvalText: z.string().min(1),
+});
+
+export type ExecutePaymentInput = z.infer<typeof executePaymentInputSchema>;
+
+export const prepareContractCallInputSchema = z.object({
+  targetAddress: evmAddressSchema,
+  callData: hexDataSchema.refine((value) => value !== "0x", "Expected non-empty calldata"),
+  sourceTokenSymbol: stableTokenSymbolSchema.default("USDT"),
+  maxTokenSpend: positiveDecimalStringSchema,
+  maxNativeFee: z.string().regex(/^(?:0|[1-9]\d*)$/, "Expected a non-negative integer string").default("0"),
+  purpose: z.string().trim().min(1).max(280),
+});
+
+export type PrepareContractCallInput = z.input<typeof prepareContractCallInputSchema>;
+export type ParsedPrepareContractCallInput = z.output<typeof prepareContractCallInputSchema>;
+
+export const routeProviderSchema = z.enum(["DIRECT", "LI.FI", "CONTRACT_CALL"]);
+
+export type RouteProvider = z.infer<typeof routeProviderSchema>;
+
+export const DIRECT_PAYMENT_ROUTE_TARGET = "0x0000000000000000000000000000000000000000";
+export const DIRECT_PAYMENT_ROUTE_CALLDATA = "0x";
+
+export interface RouteQuote {
+  routeProvider: RouteProvider;
+  sourceTokenAddress: string;
+  destinationTokenAddress: string;
+  maxAmountIn: string;
+  maxNativeFee: string;
+  routeTarget: string;
+  routeCalldata: string;
+  routeCalldataHash: string;
+  routeSummary: string;
+  estimatedFee?: string;
+  estimatedEtaSeconds?: number;
+}
+
+export function isDirectPaymentRoute(
+  sourceChainId: number,
+  destinationChainId: number,
+  sourceTokenSymbol: string,
+  destinationTokenSymbol: string,
+): boolean {
+  return sourceChainId === destinationChainId && sourceTokenSymbol === destinationTokenSymbol;
+}
+
+export function createDirectPaymentRouteQuote(request: {
+  chainId: number;
+  tokenSymbol: string;
+  amountOut: string;
+}): RouteQuote {
+  const token = getStableTokenMetadata(request.chainId, request.tokenSymbol);
+  const routeCalldata = DIRECT_PAYMENT_ROUTE_CALLDATA;
+
+  return {
+    routeProvider: "DIRECT",
+    sourceTokenAddress: token.address,
+    destinationTokenAddress: token.address,
+    maxAmountIn: request.amountOut,
+    maxNativeFee: "0",
+    routeTarget: DIRECT_PAYMENT_ROUTE_TARGET,
+    routeCalldata,
+    routeCalldataHash: createRouteCalldataHash(routeCalldata),
+    routeSummary: `Direct ${request.amountOut} ${token.symbol} transfer on ${getChainName(request.chainId)}.`,
+    estimatedFee: "0",
+    estimatedEtaSeconds: 0,
+  };
+}
+
+export interface PaymentIntentRecord {
+  id: string;
+  accountAddress: string;
+  ownerAddress: string;
+  status: PaymentIntentStatus;
+  paymentType: PaymentType;
+  sourceChainId: number;
+  destinationChainId: number;
+  sourceTokenAddress: string;
+  sourceTokenSymbol: string;
+  destinationTokenAddress: string;
+  destinationTokenSymbol: string;
+  recipientAddress: string;
+  amountOut: string;
+  maxAmountIn: string;
+  maxNativeFee: string;
+  routeProvider: RouteProvider;
+  routeTarget: string;
+  routeCalldata: string;
+  routeCalldataHash: string;
+  routeSummary: string;
+  estimatedFee?: string;
+  estimatedEtaSeconds?: number;
+  nonce: string;
+  deadline: string;
+  purpose: string;
+  approvalPhrase: string;
+  approvedAt?: string;
+  sourceTxHash?: string;
+  destinationTxHash?: string;
+  lifiTrackingId?: string;
+  errorCode?: string;
+  errorMessage?: string;
+  createdAt?: string;
+  completedAt?: string;
+}
+
+export function createRouteCalldataHash(routeCalldata: string): string {
+  const parsed = hexDataSchema.parse(routeCalldata);
+  return `0x${bytesToHex(keccak_256(hexToBytes(parsed.slice(2))))}`;
+}

package/src/payment-tracking.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+
+export const trackPaymentInputSchema = z.object({
+  paymentIntentId: z.string().trim().min(1),
+});
+
+export type TrackPaymentInput = z.infer<typeof trackPaymentInputSchema>;
+
+export const listTransactionsInputSchema = z.object({
+  limit: z.number().int().min(1).max(50).default(10),
+});
+
+export type ListTransactionsInput = z.input<typeof listTransactionsInputSchema>;
+export type ParsedListTransactionsInput = z.output<typeof listTransactionsInputSchema>;
+
+export const listPaymentEventsInputSchema = z.object({
+  paymentIntentId: z.string().trim().min(1),
+  limit: z.number().int().min(1).max(50).default(20),
+});
+
+export type ListPaymentEventsInput = z.input<typeof listPaymentEventsInputSchema>;
+export type ParsedListPaymentEventsInput = z.output<typeof listPaymentEventsInputSchema>;
+
+export interface PaymentEventRecord {
+  id: string;
+  paymentIntentId: string;
+  eventType: string;
+  message?: string;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+}

package/src/tokens.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+
+export const STABLE_TOKEN_SYMBOLS = ["USDC", "USDT"] as const;
+
+export const stableTokenSymbolSchema = z.enum(STABLE_TOKEN_SYMBOLS);
+
+export type StableTokenSymbol = z.infer<typeof stableTokenSymbolSchema>;
+
+export const STABLE_TOKEN_DECIMALS: Record<StableTokenSymbol, number> = {
+  USDC: 6,
+  USDT: 6,
+};
+
+export interface StableTokenMetadata {
+  symbol: StableTokenSymbol;
+  address: string;
+  decimals: number;
+}
+
+export type StableTokenMetadataOverrides = Partial<
+  Record<number, Partial<Record<StableTokenSymbol, Partial<Pick<StableTokenMetadata, "address" | "decimals">>>>>
+>;
+
+let configuredStableTokenMetadataOverrides: StableTokenMetadataOverrides = {};
+
+export const STABLE_TOKENS_BY_CHAIN: Record<number, Record<StableTokenSymbol, StableTokenMetadata>> = {
+  56: {
+    USDC: {
+      symbol: "USDC",
+      address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",
+      decimals: 18,
+    },
+    USDT: {
+      symbol: "USDT",
+      address: "0x55d398326f99059fF775485246999027B3197955",
+      decimals: 18,
+    },
+  },
+  97: {
+    USDC: {
+      symbol: "USDC",
+      address: "0xEC1C60D64a06896Df296438c12edD14E974FDE47",
+      decimals: 6,
+    },
+    USDT: {
+      symbol: "USDT",
+      address: "0x337610d27c682E347C9cD60BD4b3b107C9d34dDd",
+      decimals: 18,
+    },
+  },
+  8453: {
+    USDC: {
+      symbol: "USDC",
+      address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+      decimals: 6,
+    },
+    USDT: {
+      symbol: "USDT",
+      address: "0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2",
+      decimals: 6,
+    },
+  },
+};
+
+export function configureStableTokenMetadataOverrides(overrides: StableTokenMetadataOverrides): void {
+  configuredStableTokenMetadataOverrides = { ...overrides };
+}
+
+export function getStableTokenDecimals(symbol: string): number {
+  const decimals = STABLE_TOKEN_DECIMALS[symbol as StableTokenSymbol];
+  if (decimals === undefined) {
+    throw new Error(`Unsupported stable token symbol: ${symbol}`);
+  }
+  return decimals;
+}
+
+export function getStableTokenMetadata(chainId: number, symbol: string): StableTokenMetadata {
+  const parsedSymbol = stableTokenSymbolSchema.parse(symbol);
+  const metadata = STABLE_TOKENS_BY_CHAIN[chainId]?.[parsedSymbol];
+
+  if (!metadata) {
+    throw new Error(`Unsupported stable token ${parsedSymbol} on chain ${chainId}.`);
+  }
+
+  const override = configuredStableTokenMetadataOverrides[chainId]?.[parsedSymbol];
+
+  return {
+    ...metadata,
+    ...override,
+    symbol: parsedSymbol,
+  };
+}
+
+export function getStableTokenAddress(chainId: number, symbol: string): string {
+  return getStableTokenMetadata(chainId, symbol).address;
+}
+
+export function getStableTokenDecimalsForChain(chainId: number, symbol: string): number {
+  return getStableTokenMetadata(chainId, symbol).decimals;
+}

package/src/wallet-setup.ts

@@ -0,0 +1,59 @@
+import { z } from "zod";
+
+import { evmAddressSchema } from "./payment-intent.ts";
+
+export const setupIntentStatusSchema = z.enum(["PENDING", "SIGNED", "DEPLOYING", "COMPLETED", "EXPIRED", "FAILED"]);
+
+export type SetupIntentStatus = z.infer<typeof setupIntentStatusSchema>;
+
+export const prepareWalletCreationInputSchema = z.object({
+  ownerAddress: evmAddressSchema.optional(),
+});
+
+export type PrepareWalletCreationInput = z.input<typeof prepareWalletCreationInputSchema>;
+
+export const checkWalletCreationInputSchema = z.object({
+  setupIntentId: z.string().trim().min(1),
+});
+
+export type CheckWalletCreationInput = z.infer<typeof checkWalletCreationInputSchema>;
+
+export const getAgentWalletInputSchema = z.object({});
+
+export type GetAgentWalletInput = z.infer<typeof getAgentWalletInputSchema>;
+
+export const prepareRouteTargetAllowanceInputSchema = z.object({
+  routeTarget: evmAddressSchema,
+  allowed: z.boolean().default(true),
+});
+
+export type PrepareRouteTargetAllowanceInput = z.input<typeof prepareRouteTargetAllowanceInputSchema>;
+
+export const checkRouteTargetAllowanceInputSchema = z.object({
+  routeTarget: evmAddressSchema,
+});
+
+export type CheckRouteTargetAllowanceInput = z.infer<typeof checkRouteTargetAllowanceInputSchema>;
+
+export const setupSignatureSchema = z.string().regex(/^0x[a-fA-F0-9]{130}$/, "Expected an EVM signature");
+
+export const completeWalletSetupInputSchema = z.object({
+  setupIntentId: z.string().trim().min(1),
+  signature: setupSignatureSchema,
+});
+
+export type CompleteWalletSetupInput = z.infer<typeof completeWalletSetupInputSchema>;
+
+export interface SetupIntentRecord {
+  id: string;
+  ownerAddress?: string;
+  executorAddress: string;
+  messageToSign: string;
+  signature?: string;
+  status: SetupIntentStatus;
+  expiresAt: string;
+  accountAddress?: string;
+  errorCode?: string;
+  errorMessage?: string;
+  completedAt?: string;
+}

package/src/x402.ts

@@ -0,0 +1,204 @@
+import { z } from "zod";
+
+import { getChainName } from "./chains.ts";
+import { evmAddressSchema, preparePaymentInputSchema } from "./payment-intent.ts";
+import { getStableTokenMetadata, STABLE_TOKEN_SYMBOLS, stableTokenSymbolSchema } from "./tokens.ts";
+import type { StableTokenSymbol } from "./tokens.ts";
+
+const positiveIntegerStringSchema = z.string().regex(/^[1-9]\d*$/, "Expected a positive integer string");
+
+export const parseX402PaymentRequiredInputSchema = z.object({
+  paymentRequired: z.union([z.string().trim().min(1), z.record(z.string(), z.unknown())]),
+  sourceTokenSymbol: stableTokenSymbolSchema.default("USDT"),
+});
+
+export type ParseX402PaymentRequiredInput = z.input<typeof parseX402PaymentRequiredInputSchema>;
+
+const x402ResourceInfoSchema = z
+  .object({
+    url: z.string().url(),
+    description: z.string().optional(),
+    mimeType: z.string().optional(),
+    serviceName: z.string().optional(),
+  })
+  .passthrough();
+
+const x402PaymentRequirementSchema = z
+  .object({
+    scheme: z.string(),
+    network: z.string(),
+    amount: positiveIntegerStringSchema,
+    asset: z.string(),
+    payTo: evmAddressSchema,
+    maxTimeoutSeconds: z.number().int().positive(),
+    extra: z.record(z.string(), z.unknown()).optional(),
+  })
+  .passthrough();
+
+const x402PaymentRequiredSchema = z
+  .object({
+    x402Version: z.literal(2),
+    error: z.string().optional(),
+    resource: x402ResourceInfoSchema,
+    accepts: z.array(x402PaymentRequirementSchema).min(1),
+    extensions: z.record(z.string(), z.unknown()).optional(),
+  })
+  .passthrough();
+
+export interface ParsedX402PaymentRequired {
+  x402Version: 2;
+  resource: {
+    url: string;
+    description?: string;
+    serviceName?: string;
+    mimeType?: string;
+  };
+  selectedRequirement: {
+    scheme: "exact";
+    network: string;
+    chainId: number;
+    chain: string;
+    asset: string;
+    tokenSymbol: StableTokenSymbol;
+    payTo: string;
+    amountAtomic: string;
+    amount: string;
+    maxTimeoutSeconds: number;
+  };
+  paymentInput: {
+    recipientAddress: string;
+    destinationChainId: number;
+    destinationChain: string;
+    destinationTokenSymbol: StableTokenSymbol;
+    amountOut: string;
+    purpose: string;
+    sourceTokenSymbol: StableTokenSymbol;
+    paymentType: "X402_PAYMENT";
+  };
+  standardX402SignatureRequired: true;
+}
+
+export function parseX402PaymentRequired(rawInput: ParseX402PaymentRequiredInput): ParsedX402PaymentRequired {
+  const input = parseX402PaymentRequiredInputSchema.parse(rawInput);
+  const paymentRequired = x402PaymentRequiredSchema.parse(decodePaymentRequired(input.paymentRequired));
+  const selected = paymentRequired.accepts.map(toSupportedRequirement).find((requirement) => requirement !== null);
+
+  if (!selected) {
+    throw new Error("No AgentPay-supported x402 payment requirement was found.");
+  }
+
+  const purpose = createX402Purpose(paymentRequired.resource);
+  const paymentInput = preparePaymentInputSchema.parse({
+    recipientAddress: selected.payTo,
+    destinationChainId: selected.chainId,
+    destinationTokenSymbol: selected.tokenSymbol,
+    amountOut: selected.amount,
+    purpose,
+    sourceTokenSymbol: input.sourceTokenSymbol,
+    paymentType: "X402_PAYMENT",
+  });
+
+  return {
+    x402Version: 2,
+    resource: {
+      url: paymentRequired.resource.url,
+      description: paymentRequired.resource.description,
+      serviceName: paymentRequired.resource.serviceName,
+      mimeType: paymentRequired.resource.mimeType,
+    },
+    selectedRequirement: selected,
+    paymentInput: {
+      recipientAddress: paymentInput.recipientAddress,
+      destinationChainId: paymentInput.destinationChainId,
+      destinationChain: getChainName(paymentInput.destinationChainId),
+      destinationTokenSymbol: paymentInput.destinationTokenSymbol,
+      amountOut: paymentInput.amountOut,
+      purpose: paymentInput.purpose,
+      sourceTokenSymbol: paymentInput.sourceTokenSymbol,
+      paymentType: "X402_PAYMENT",
+    },
+    standardX402SignatureRequired: true,
+  };
+}
+
+function decodePaymentRequired(paymentRequired: string | Record<string, unknown>): unknown {
+  if (typeof paymentRequired !== "string") {
+    return paymentRequired;
+  }
+
+  const trimmed = paymentRequired.trim();
+  const json = trimmed.startsWith("{") ? trimmed : Buffer.from(trimmed, "base64").toString("utf8");
+
+  return JSON.parse(json) as unknown;
+}
+
+function toSupportedRequirement(requirement: z.infer<typeof x402PaymentRequirementSchema>):
+  | ParsedX402PaymentRequired["selectedRequirement"]
+  | null {
+  if (requirement.scheme !== "exact") {
+    return null;
+  }
+
+  const chainId = parseEip155Network(requirement.network);
+
+  if (!chainId) {
+    return null;
+  }
+
+  const tokenSymbol = findStableTokenSymbolByAddress(chainId, requirement.asset);
+
+  if (!tokenSymbol) {
+    return null;
+  }
+
+  const token = getStableTokenMetadata(chainId, tokenSymbol);
+
+  return {
+    scheme: "exact",
+    network: requirement.network,
+    chainId,
+    chain: getChainName(chainId),
+    asset: requirement.asset,
+    tokenSymbol,
+    payTo: requirement.payTo,
+    amountAtomic: requirement.amount,
+    amount: atomicToDecimal(BigInt(requirement.amount), token.decimals),
+    maxTimeoutSeconds: requirement.maxTimeoutSeconds,
+  };
+}
+
+function parseEip155Network(network: string): number | null {
+  const match = network.match(/^eip155:(\d+)$/);
+
+  return match ? Number(match[1]) : null;
+}
+
+function findStableTokenSymbolByAddress(chainId: number, asset: string): StableTokenSymbol | null {
+  const normalizedAsset = asset.toLowerCase();
+
+  for (const symbol of STABLE_TOKEN_SYMBOLS) {
+    try {
+      if (getStableTokenMetadata(chainId, symbol).address.toLowerCase() === normalizedAsset) {
+        return symbol;
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+function atomicToDecimal(amount: bigint, decimals: number): string {
+  const padded = amount.toString().padStart(decimals + 1, "0");
+  const whole = padded.slice(0, -decimals);
+  const fractional = padded.slice(-decimals).replace(/0+$/, "");
+
+  return fractional ? `${whole}.${fractional}` : whole;
+}
+
+function createX402Purpose(resource: z.infer<typeof x402ResourceInfoSchema>): string {
+  const details = [resource.serviceName, resource.description].filter(Boolean).join(": ") || resource.url;
+
+  return `x402 payment for ${details}`.slice(0, 280);
+}