@agentpay-ai/shared 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,22 @@
+# @agentpay-ai/shared
+
+Shared schemas, chain metadata, token helpers, and intent types for AgentPay.
+
+Use this package when building AgentPay-compatible tools that need the same validation rules as the MCP server, setup web, and CLI.
+
+## Included Modules
+
+- Approval phrase parsing and payment intent types.
+- X Layer stablecoin metadata and balance helpers.
+- Wallet setup, invoice, x402, x402 Bazaar discovery, account admin, and payment tracking schemas, including x402 `PAYMENT-RESPONSE` and `payment-identifier` proof helpers.
+- Route calldata hashing helpers used by guarded contract calls.
+
+## Example
+
+```ts
+import { preparePaymentInputSchema } from "@agentpay-ai/shared";
+
+const input = preparePaymentInputSchema.parse(candidatePayment);
+```
+
+AgentPay validates untrusted inputs at runtime boundaries with Zod. Keep that pattern when extending the package.

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@agentpay-ai/shared",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
   },
   "files": [
+    "README.md",
     "src/account-admin.ts",
     "src/approval.ts",
     "src/balance.ts",
@@ -16,7 +17,8 @@
     "src/payment-tracking.ts",
     "src/tokens.ts",
     "src/wallet-setup.ts",
-    "src/x402.ts"
+    "src/x402.ts",
+    "src/x402-bazaar.ts"
   ],
   "publishConfig": {
     "access": "public"

package/src/account-admin.ts

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

package/src/balance.ts

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

package/src/chains.ts

@@ -1,17 +1,19 @@
+import { z } from "zod";
+
 export const SUPPORTED_CHAINS = {
-  56: {
-    id: 56,
-    name: "BNB Chain",
+  196: {
+    id: 196,
+    name: "X Layer",
     nativeCurrency: {
-      symbol: "BNB",
+      symbol: "OKB",
       decimals: 18,
     },
   },
-  97: {
-    id: 97,
-    name: "BNB Chain Testnet",
+  1952: {
+    id: 1952,
+    name: "X Layer Testnet",
     nativeCurrency: {
-      symbol: "tBNB",
+      symbol: "OKB",
       decimals: 18,
     },
   },
@@ -28,6 +30,35 @@ export const SUPPORTED_CHAINS = {
 export type SupportedChainId = keyof typeof SUPPORTED_CHAINS;
 export type NativeCurrency = (typeof SUPPORTED_CHAINS)[SupportedChainId]["nativeCurrency"];
 
+export const X_LAYER_NETWORK_CHAIN_IDS = {
+  mainnet: 196,
+  testnet: 1952,
+} as const;
+
+export const xLayerNetworkSchema = z.enum(["mainnet", "testnet"]);
+export const xLayerHomeChainIdSchema = z.union([z.literal(196), z.literal(1952)]);
+export const networkSelectionShape = {
+  network: xLayerNetworkSchema.optional(),
+  homeChainId: xLayerHomeChainIdSchema.optional(),
+} as const;
+
+export type XLayerNetwork = z.infer<typeof xLayerNetworkSchema>;
+export type XLayerHomeChainId = z.infer<typeof xLayerHomeChainIdSchema>;
+export type NetworkSelectionInput = {
+  network?: XLayerNetwork;
+  homeChainId?: XLayerHomeChainId;
+};
+
+export function resolveXLayerHomeChainId(input: NetworkSelectionInput, fallbackHomeChainId: XLayerHomeChainId = 196): XLayerHomeChainId {
+  const networkHomeChainId = input.network ? X_LAYER_NETWORK_CHAIN_IDS[input.network] : undefined;
+
+  if (networkHomeChainId !== undefined && input.homeChainId !== undefined && networkHomeChainId !== input.homeChainId) {
+    throw new Error(`Network ${input.network} maps to chain ${networkHomeChainId}, but homeChainId ${input.homeChainId} was provided.`);
+  }
+
+  return input.homeChainId ?? networkHomeChainId ?? fallbackHomeChainId;
+}
+
 export function getChainName(chainId: number): string {
   return SUPPORTED_CHAINS[chainId as SupportedChainId]?.name ?? `Chain ${chainId}`;
 }

package/src/index.ts

@@ -8,3 +8,4 @@ export * from "./payment-tracking.ts";
 export * from "./tokens.ts";
 export * from "./wallet-setup.ts";
 export * from "./x402.ts";
+export * from "./x402-bazaar.ts";

package/src/invoice.ts

@@ -2,11 +2,11 @@ import { z } from "zod";
 
 import { getChainName } from "./chains.ts";
 import { preparePaymentInputSchema } from "./payment-intent.ts";
-import { stableTokenSymbolSchema } from "./tokens.ts";
+import { stableTokenSymbolSchema, type StableTokenSymbol } from "./tokens.ts";
 
 export const parseInvoicePaymentInputSchema = z.object({
   invoice: z.string().trim().min(1),
-  sourceTokenSymbol: stableTokenSymbolSchema.default("USDT"),
+  sourceTokenSymbol: stableTokenSymbolSchema.default("USDT0"),
 });
 
 export type ParseInvoicePaymentInput = z.input<typeof parseInvoicePaymentInputSchema>;
@@ -16,10 +16,10 @@ export interface ParsedInvoicePayment {
   recipientAddress: string;
   destinationChainId: number;
   destinationChain: string;
-  destinationTokenSymbol: "USDC" | "USDT";
+  destinationTokenSymbol: StableTokenSymbol;
   amountOut: string;
   purpose: string;
-  sourceTokenSymbol: "USDC" | "USDT";
+  sourceTokenSymbol: StableTokenSymbol;
   paymentType: "INVOICE_PAYMENT";
 }
 
@@ -101,30 +101,30 @@ function parseDestinationChainId(value: string | undefined): number | undefined
 
   const normalized = normalizeKey(value);
   const knownChains: Record<string, number> = {
+    xlayer: 196,
+    xlayermainnet: 196,
+    xlayertestnet: 1952,
     base: 8453,
-    bnbchain: 56,
-    bnb: 56,
-    bsc: 56,
   };
 
   return knownChains[normalized];
 }
 
-function parseToken(value: string | undefined): "USDC" | "USDT" | undefined {
+function parseToken(value: string | undefined): StableTokenSymbol | undefined {
   if (!value) {
     return undefined;
   }
 
-  return stableTokenSymbolSchema.parse(value.trim().toUpperCase());
+  return stableTokenSymbolSchema.parse(normalizeTokenSymbol(value));
 }
 
 function parsePaymentFields(candidate: {
   recipientAddress: string | undefined;
   destinationChainId: number | undefined;
-  destinationTokenSymbol: "USDC" | "USDT" | undefined;
+  destinationTokenSymbol: StableTokenSymbol | undefined;
   amountOut: string | undefined;
   purpose: string | undefined;
-  sourceTokenSymbol: "USDC" | "USDT" | undefined;
+  sourceTokenSymbol: StableTokenSymbol | undefined;
 }) {
   const parsed = preparePaymentInputSchema.safeParse(candidate);
 
@@ -142,3 +142,7 @@ function invoicePurpose(invoiceId: string | undefined): string | undefined {
 function normalizeKey(value: string): string {
   return value.toLowerCase().replace(/[^a-z0-9]/g, "");
 }
+
+function normalizeTokenSymbol(value: string): string {
+  return value.trim().toUpperCase().replace("USD₮0", "USDT0");
+}

package/src/payment-intent.ts

@@ -2,7 +2,7 @@ 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 { getChainName, networkSelectionShape } from "./chains.ts";
 import { getStableTokenMetadata, stableTokenSymbolSchema } from "./tokens.ts";
 
 const addressPattern = /^0x[a-fA-F0-9]{40}$/;
@@ -44,8 +44,9 @@ export const preparePaymentInputSchema = z.object({
   destinationTokenSymbol: stableTokenSymbolSchema,
   amountOut: positiveDecimalStringSchema,
   purpose: z.string().trim().min(1).max(280),
-  sourceTokenSymbol: stableTokenSymbolSchema.default("USDT"),
+  sourceTokenSymbol: stableTokenSymbolSchema.default("USDT0"),
   paymentType: stablecoinPaymentTypeSchema.default("WALLET_PAYMENT"),
+  ...networkSelectionShape,
 });
 
 export const quotePaymentRouteInputSchema = preparePaymentInputSchema.omit({ purpose: true, paymentType: true });
@@ -66,10 +67,11 @@ 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"),
+  sourceTokenSymbol: stableTokenSymbolSchema.default("USDT0"),
   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),
+  ...networkSelectionShape,
 });
 
 export type PrepareContractCallInput = z.input<typeof prepareContractCallInputSchema>;

package/src/tokens.ts

@@ -1,12 +1,14 @@
 import { z } from "zod";
 
-export const STABLE_TOKEN_SYMBOLS = ["USDC", "USDT"] as const;
+export const STABLE_TOKEN_SYMBOLS = ["USDT0", "USDC", "USDT"] as const;
+export const DEFAULT_STABLE_TOKEN_SYMBOLS = ["USDT0", "USDC"] as const satisfies readonly StableTokenSymbol[];
 
 export const stableTokenSymbolSchema = z.enum(STABLE_TOKEN_SYMBOLS);
 
 export type StableTokenSymbol = z.infer<typeof stableTokenSymbolSchema>;
 
 export const STABLE_TOKEN_DECIMALS: Record<StableTokenSymbol, number> = {
+  USDT0: 6,
   USDC: 6,
   USDT: 6,
 };
@@ -23,31 +25,25 @@ export type StableTokenMetadataOverrides = Partial<
 
 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,
+export const STABLE_TOKENS_BY_CHAIN: Record<number, Partial<Record<StableTokenSymbol, StableTokenMetadata>>> = {
+  196: {
+    USDT0: {
+      symbol: "USDT0",
+      address: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736",
+      decimals: 6,
     },
-  },
-  97: {
     USDC: {
       symbol: "USDC",
-      address: "0xEC1C60D64a06896Df296438c12edD14E974FDE47",
+      address: "0x74b7F16337b8972027F6196A17a631aC6dE26d22",
       decimals: 6,
     },
     USDT: {
       symbol: "USDT",
-      address: "0x337610d27c682E347C9cD60BD4b3b107C9d34dDd",
-      decimals: 18,
+      address: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736",
+      decimals: 6,
     },
   },
+  1952: {},
   8453: {
     USDC: {
       symbol: "USDC",
@@ -77,15 +73,18 @@ export function getStableTokenDecimals(symbol: string): number {
 export function getStableTokenMetadata(chainId: number, symbol: string): StableTokenMetadata {
   const parsedSymbol = stableTokenSymbolSchema.parse(symbol);
   const metadata = STABLE_TOKENS_BY_CHAIN[chainId]?.[parsedSymbol];
+  const override = configuredStableTokenMetadataOverrides[chainId]?.[parsedSymbol];
 
-  if (!metadata) {
+  if (!metadata && !override?.address) {
     throw new Error(`Unsupported stable token ${parsedSymbol} on chain ${chainId}.`);
   }
 
-  const override = configuredStableTokenMetadataOverrides[chainId]?.[parsedSymbol];
-
   return {
-    ...metadata,
+    ...(metadata ?? {
+      symbol: parsedSymbol,
+      address: override?.address ?? "",
+      decimals: STABLE_TOKEN_DECIMALS[parsedSymbol],
+    }),
     ...override,
     symbol: parsedSymbol,
   };
@@ -98,3 +97,14 @@ export function getStableTokenAddress(chainId: number, symbol: string): string {
 export function getStableTokenDecimalsForChain(chainId: number, symbol: string): number {
   return getStableTokenMetadata(chainId, symbol).decimals;
 }
+
+export function getSupportedStableTokenMetadataForChain(chainId: number): StableTokenMetadata[] {
+  const staticTokens = STABLE_TOKENS_BY_CHAIN[chainId] ?? {};
+  const overrideTokens = configuredStableTokenMetadataOverrides[chainId] ?? {};
+  const symbols = new Set<StableTokenSymbol>([
+    ...(Object.keys(staticTokens) as StableTokenSymbol[]),
+    ...(Object.keys(overrideTokens) as StableTokenSymbol[]),
+  ]);
+
+  return [...symbols].map((symbol) => getStableTokenMetadata(chainId, symbol));
+}

package/src/wallet-setup.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 
+import { networkSelectionShape } from "./chains.ts";
 import { evmAddressSchema } from "./payment-intent.ts";
 
 export const setupIntentStatusSchema = z.enum(["PENDING", "SIGNED", "DEPLOYING", "COMPLETED", "EXPIRED", "FAILED"]);
@@ -8,6 +9,7 @@ export type SetupIntentStatus = z.infer<typeof setupIntentStatusSchema>;
 
 export const prepareWalletCreationInputSchema = z.object({
   ownerAddress: evmAddressSchema.optional(),
+  ...networkSelectionShape,
 });
 
 export type PrepareWalletCreationInput = z.input<typeof prepareWalletCreationInputSchema>;
@@ -18,19 +20,23 @@ export const checkWalletCreationInputSchema = z.object({
 
 export type CheckWalletCreationInput = z.infer<typeof checkWalletCreationInputSchema>;
 
-export const getAgentWalletInputSchema = z.object({});
+export const getAgentWalletInputSchema = z.object({
+  ...networkSelectionShape,
+});
 
 export type GetAgentWalletInput = z.infer<typeof getAgentWalletInputSchema>;
 
 export const prepareRouteTargetAllowanceInputSchema = z.object({
   routeTarget: evmAddressSchema,
   allowed: z.boolean().default(true),
+  ...networkSelectionShape,
 });
 
 export type PrepareRouteTargetAllowanceInput = z.input<typeof prepareRouteTargetAllowanceInputSchema>;
 
 export const checkRouteTargetAllowanceInputSchema = z.object({
   routeTarget: evmAddressSchema,
+  ...networkSelectionShape,
 });
 
 export type CheckRouteTargetAllowanceInput = z.infer<typeof checkRouteTargetAllowanceInputSchema>;
@@ -56,4 +62,5 @@ export interface SetupIntentRecord {
   errorCode?: string;
   errorMessage?: string;
   completedAt?: string;
+  homeChainId?: number;
 }

package/src/x402-bazaar.ts

@@ -0,0 +1,273 @@
+import { z } from "zod";
+
+const positiveIntegerStringSchema = z.string().regex(/^[1-9]\d*$/, "Expected a positive integer string");
+const httpMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET");
+const bazaarResourceTypeSchema = z.enum(["http", "mcp"]);
+const scalarParameterSchema = z.union([z.string(), z.number(), z.boolean()]);
+
+const x402BazaarPaymentRequirementSchema = z
+  .object({
+    scheme: z.string(),
+    network: z.string(),
+    amount: positiveIntegerStringSchema,
+    asset: z.string(),
+    payTo: z.string(),
+    maxTimeoutSeconds: z.number().int().positive(),
+    extra: z.record(z.string(), z.unknown()).optional(),
+  })
+  .passthrough();
+
+export const x402BazaarResourceSchema = z
+  .object({
+    resource: z.string().url(),
+    type: bazaarResourceTypeSchema,
+    x402Version: z.literal(2),
+    accepts: z.array(x402BazaarPaymentRequirementSchema).min(1),
+    lastUpdated: z.string().optional(),
+    description: z.string().optional(),
+    mimeType: z.string().optional(),
+    serviceName: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    iconUrl: z.string().url().optional(),
+    extensions: z.record(z.string(), z.unknown()).optional(),
+  })
+  .passthrough();
+
+export const searchX402ServicesInputSchema = z.object({
+  query: z.string().trim().min(1),
+  type: bazaarResourceTypeSchema.default("http"),
+  network: z.string().trim().min(1).optional(),
+  limit: z.number().int().min(1).max(20).default(5),
+  cursor: z.string().trim().min(1).optional(),
+});
+
+export const prepareX402ServiceRequestInputSchema = z.object({
+  resource: x402BazaarResourceSchema,
+  parameters: z.record(z.string(), scalarParameterSchema).default({}),
+  headers: z.record(z.string(), z.string()).default({}),
+  body: z.unknown().optional(),
+});
+
+export type X402BazaarResource = z.output<typeof x402BazaarResourceSchema>;
+export type X402BazaarPaymentRequirement = z.output<typeof x402BazaarPaymentRequirementSchema>;
+export type SearchX402ServicesInput = z.input<typeof searchX402ServicesInputSchema>;
+export type ParsedSearchX402ServicesInput = z.output<typeof searchX402ServicesInputSchema>;
+export type PrepareX402ServiceRequestInput = z.input<typeof prepareX402ServiceRequestInputSchema>;
+export type ParsedPrepareX402ServiceRequestInput = z.output<typeof prepareX402ServiceRequestInputSchema>;
+
+export interface X402BazaarPaymentRequiredObject extends Record<string, unknown> {
+  x402Version: 2;
+  resource: {
+    url: string;
+    description?: string;
+    serviceName?: string;
+    mimeType?: string;
+  };
+  accepts: X402BazaarPaymentRequirement[];
+  extensions?: Record<string, unknown>;
+}
+
+export interface BuiltX402BazaarHttpRequest {
+  status: "REQUEST_READY" | "NEEDS_INPUT";
+  request?: {
+    url: string;
+    method: z.output<typeof httpMethodSchema>;
+    headers: Record<string, string>;
+    body?: string;
+  };
+  paymentRequired?: X402BazaarPaymentRequiredObject;
+  missingParameters: string[];
+}
+
+export function normalizeX402BazaarResource(rawResource: unknown): X402BazaarResource {
+  return x402BazaarResourceSchema.parse(rawResource);
+}
+
+export function buildX402BazaarHttpRequest(request: {
+  resource: X402BazaarResource;
+  parameters: Record<string, string | number | boolean>;
+  headers: Record<string, string>;
+  body?: unknown;
+}): BuiltX402BazaarHttpRequest {
+  if (request.resource.type !== "http") {
+    throw new Error("prepare_x402_service_request currently supports Bazaar HTTP resources only.");
+  }
+
+  const input = getBazaarInput(request.resource);
+  const method = httpMethodSchema.parse(asString(input.method)?.toUpperCase() ?? "GET");
+  const missingParameters = new Set<string>();
+  const usedParameters = new Set<string>();
+  const routeTemplate = asString(input.routeTemplate) ?? request.resource.resource;
+  const templatedPath = applyPathParameters(routeTemplate, request.parameters, usedParameters, missingParameters);
+  const url = new URL(resolveRouteTemplate(templatedPath, request.resource.resource));
+  const queryParams = asRecord(input.queryParams);
+
+  for (const key of Object.keys(queryParams ?? {})) {
+    usedParameters.add(key);
+    if (!Object.hasOwn(request.parameters, key)) {
+      missingParameters.add(key);
+    } else {
+      url.searchParams.set(key, String(request.parameters[key]));
+    }
+  }
+
+  for (const key of getJsonSchemaRequiredKeys(input)) {
+    if (!Object.hasOwn(request.parameters, key) && request.body === undefined) {
+      missingParameters.add(key);
+    }
+  }
+
+  if (missingParameters.size > 0) {
+    return {
+      status: "NEEDS_INPUT",
+      missingParameters: [...missingParameters].sort(),
+    };
+  }
+
+  const headers = { ...request.headers };
+  const body = createRequestBody(method, request.body, request.parameters, usedParameters, headers);
+  const requestUrl = url.toString();
+
+  return {
+    status: "REQUEST_READY",
+    request: omitUndefined({
+      url: requestUrl,
+      method,
+      headers,
+      body,
+    }) as BuiltX402BazaarHttpRequest["request"],
+    paymentRequired: createPaymentRequiredObject(request.resource, requestUrl),
+    missingParameters: [],
+  };
+}
+
+export function getX402BazaarRequiredParameters(resource: X402BazaarResource): string[] {
+  const input = getBazaarInput(resource);
+  const routeTemplate = asString(input.routeTemplate) ?? resource.resource;
+  return [...new Set([...getPathParameterNames(routeTemplate), ...Object.keys(asRecord(input.queryParams) ?? {}), ...getJsonSchemaRequiredKeys(input)])].sort();
+}
+
+export function getX402BazaarHttpMethod(resource: X402BazaarResource): string | undefined {
+  const input = getBazaarInput(resource);
+  return asString(input.method)?.toUpperCase();
+}
+
+function createPaymentRequiredObject(resource: X402BazaarResource, requestUrl: string): X402BazaarPaymentRequiredObject {
+  return omitUndefined({
+    x402Version: 2,
+    resource: omitUndefined({
+      url: requestUrl,
+      description: resource.description,
+      serviceName: resource.serviceName,
+      mimeType: resource.mimeType,
+    }),
+    accepts: resource.accepts,
+    extensions: resource.extensions,
+  }) as X402BazaarPaymentRequiredObject;
+}
+
+function createRequestBody(
+  method: z.output<typeof httpMethodSchema>,
+  rawBody: unknown,
+  parameters: Record<string, string | number | boolean>,
+  usedParameters: Set<string>,
+  headers: Record<string, string>,
+): string | undefined {
+  if (method === "GET" || method === "DELETE") {
+    return undefined;
+  }
+
+  if (rawBody !== undefined) {
+    return typeof rawBody === "string" ? rawBody : JSON.stringify(rawBody);
+  }
+
+  const unusedParameters = Object.fromEntries(
+    Object.entries(parameters).filter(([key]) => !usedParameters.has(key)),
+  );
+
+  if (Object.keys(unusedParameters).length === 0) {
+    return undefined;
+  }
+
+  if (!hasHeader(headers, "content-type")) {
+    headers["Content-Type"] = "application/json";
+  }
+
+  return JSON.stringify(unusedParameters);
+}
+
+function applyPathParameters(
+  routeTemplate: string,
+  parameters: Record<string, string | number | boolean>,
+  usedParameters: Set<string>,
+  missingParameters: Set<string>,
+): string {
+  return routeTemplate
+    .replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, key: string) =>
+      replacePathParameter(key, parameters, usedParameters, missingParameters),
+    )
+    .replace(/\[([A-Za-z_][A-Za-z0-9_]*)\]/g, (_match, key: string) =>
+      replacePathParameter(key, parameters, usedParameters, missingParameters),
+    )
+    .replace(/\/:([A-Za-z_][A-Za-z0-9_]*)/g, (_match, key: string) =>
+      `/${replacePathParameter(key, parameters, usedParameters, missingParameters)}`,
+    );
+}
+
+function replacePathParameter(
+  key: string,
+  parameters: Record<string, string | number | boolean>,
+  usedParameters: Set<string>,
+  missingParameters: Set<string>,
+): string {
+  usedParameters.add(key);
+  if (!Object.hasOwn(parameters, key)) {
+    missingParameters.add(key);
+    return `{${key}}`;
+  }
+
+  return encodeURIComponent(String(parameters[key]));
+}
+
+function getPathParameterNames(routeTemplate: string): string[] {
+  return [
+    ...routeTemplate.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g),
+    ...routeTemplate.matchAll(/\[([A-Za-z_][A-Za-z0-9_]*)\]/g),
+    ...routeTemplate.matchAll(/\/:([A-Za-z_][A-Za-z0-9_]*)/g),
+  ].map((match) => match[1]!);
+}
+
+function resolveRouteTemplate(routeTemplate: string, resourceUrl: string): string {
+  return new URL(routeTemplate, resourceUrl).toString();
+}
+
+function getJsonSchemaRequiredKeys(input: Record<string, unknown>): string[] {
+  const inputSchema = asRecord(input.inputSchema);
+  const required = inputSchema?.required;
+  return Array.isArray(required) ? required.filter((key): key is string => typeof key === "string") : [];
+}
+
+function getBazaarInput(resource: X402BazaarResource): Record<string, unknown> {
+  const extensions = asRecord(resource.extensions);
+  const bazaar = asRecord(extensions?.bazaar);
+  const info = asRecord(bazaar?.info);
+  return asRecord(info?.input) ?? {};
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function hasHeader(headers: Record<string, string>, headerName: string): boolean {
+  return Object.keys(headers).some((name) => name.toLowerCase() === headerName.toLowerCase());
+}
+
+function omitUndefined<T extends Record<string, unknown>>(record: T): Partial<T> {
+  return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as Partial<T>;
+}

package/src/x402.ts

@@ -1,19 +1,41 @@
 import { z } from "zod";
+import { keccak_256 } from "@noble/hashes/sha3.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
 
 import { getChainName } from "./chains.ts";
-import { evmAddressSchema, preparePaymentInputSchema } from "./payment-intent.ts";
+import { evmAddressSchema, preparePaymentInputSchema, type PaymentIntentRecord } 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");
+const PAYMENT_IDENTIFIER = "payment-identifier";
+const paymentIdentifierSchema = z.string().regex(/^[A-Za-z0-9_-]{16,128}$/);
 
 export const parseX402PaymentRequiredInputSchema = z.object({
   paymentRequired: z.union([z.string().trim().min(1), z.record(z.string(), z.unknown())]),
-  sourceTokenSymbol: stableTokenSymbolSchema.default("USDT"),
+  sourceTokenSymbol: stableTokenSymbolSchema.default("USDT0"),
 });
 
 export type ParseX402PaymentRequiredInput = z.input<typeof parseX402PaymentRequiredInputSchema>;
 
+const retryX402HttpMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).default("GET");
+
+export const retryX402RequestInputSchema = z.object({
+  paymentRequired: parseX402PaymentRequiredInputSchema.shape.paymentRequired,
+  paymentIntentId: z.string().trim().min(1),
+  request: z
+    .object({
+      url: z.string().url().optional(),
+      method: retryX402HttpMethodSchema,
+      headers: z.record(z.string(), z.string()).default({}),
+      body: z.string().optional(),
+    })
+    .default({ method: "GET", headers: {} }),
+});
+
+export type RetryX402RequestInput = z.input<typeof retryX402RequestInputSchema>;
+export type ParsedRetryX402RequestInput = z.output<typeof retryX402RequestInputSchema>;
+
 const x402ResourceInfoSchema = z
   .object({
     url: z.string().url(),
@@ -75,13 +97,51 @@ export interface ParsedX402PaymentRequired {
     sourceTokenSymbol: StableTokenSymbol;
     paymentType: "X402_PAYMENT";
   };
+  extensions?: {
+    "payment-identifier"?: {
+      info: {
+        required: boolean;
+      };
+    };
+  };
   standardX402SignatureRequired: true;
 }
 
+export interface AgentPayX402PaymentProof {
+  x402Version: 2;
+  scheme: "agentpay-receipt";
+  paymentIntentId: string;
+  paymentType: "X402_PAYMENT";
+  payer: string;
+  ownerAddress: string;
+  resourceUrl: string;
+  requirementHash: string;
+  network: string;
+  chainId: number;
+  asset: string;
+  payTo: string;
+  amount: string;
+  amountDecimal: string;
+  sourceTxHash: string;
+  destinationTxHash?: string;
+  settlementTxHash: string;
+  completedAt?: string;
+  paymentIdentifier?: string;
+  extensions?: {
+    "payment-identifier"?: {
+      info: {
+        required: boolean;
+        id: string;
+      };
+    };
+  };
+}
+
 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);
+  const paymentIdentifierExtension = parsePaymentIdentifierExtension(paymentRequired.extensions);
 
   if (!selected) {
     throw new Error("No AgentPay-supported x402 payment requirement was found.");
@@ -117,10 +177,84 @@ export function parseX402PaymentRequired(rawInput: ParseX402PaymentRequiredInput
       sourceTokenSymbol: paymentInput.sourceTokenSymbol,
       paymentType: "X402_PAYMENT",
     },
+    ...(paymentIdentifierExtension
+      ? {
+          extensions: {
+            [PAYMENT_IDENTIFIER]: paymentIdentifierExtension,
+          },
+        }
+      : {}),
     standardX402SignatureRequired: true,
   };
 }
 
+export function createAgentPayX402PaymentHeader(request: {
+  parsed: ParsedX402PaymentRequired;
+  paymentIntent: PaymentIntentRecord;
+}): string {
+  return encodeBase64UrlJson(createAgentPayX402PaymentProof(request));
+}
+
+export function decodeAgentPayX402PaymentHeader(header: string): AgentPayX402PaymentProof {
+  const decoded = JSON.parse(Buffer.from(header, "base64url").toString("utf8")) as unknown;
+  return agentPayX402PaymentProofSchema.parse(decoded);
+}
+
+export function createAgentPayX402PaymentProof(request: {
+  parsed: ParsedX402PaymentRequired;
+  paymentIntent: PaymentIntentRecord;
+}): AgentPayX402PaymentProof {
+  const { parsed, paymentIntent } = request;
+  const selected = parsed.selectedRequirement;
+
+  validateCompletedX402Intent(parsed, paymentIntent);
+
+  const settlementTxHash = paymentIntent.destinationTxHash ?? paymentIntent.sourceTxHash;
+  const paymentIdentifierExtension = parsed.extensions?.[PAYMENT_IDENTIFIER];
+  const paymentIdentifier = paymentIdentifierExtension ? createPaymentIdentifier(paymentIntent.id) : undefined;
+
+  return {
+    x402Version: 2,
+    scheme: "agentpay-receipt",
+    paymentIntentId: paymentIntent.id,
+    paymentType: "X402_PAYMENT",
+    payer: paymentIntent.accountAddress,
+    ownerAddress: paymentIntent.ownerAddress,
+    resourceUrl: parsed.resource.url,
+    requirementHash: createX402RequirementHash(parsed),
+    network: selected.network,
+    chainId: selected.chainId,
+    asset: selected.asset,
+    payTo: selected.payTo,
+    amount: selected.amountAtomic,
+    amountDecimal: selected.amount,
+    sourceTxHash: paymentIntent.sourceTxHash!,
+    ...(paymentIntent.destinationTxHash ? { destinationTxHash: paymentIntent.destinationTxHash } : {}),
+    settlementTxHash: settlementTxHash!,
+    ...(paymentIntent.completedAt ? { completedAt: paymentIntent.completedAt } : {}),
+    ...(paymentIdentifier
+      ? {
+          paymentIdentifier,
+          extensions: {
+            [PAYMENT_IDENTIFIER]: {
+              info: {
+                required: paymentIdentifierExtension!.info.required,
+                id: paymentIdentifier,
+              },
+            },
+          },
+        }
+      : {}),
+  };
+}
+
+export function createX402RequirementHash(parsed: ParsedX402PaymentRequired): string {
+  return `0x${bytesToHex(keccak_256(new TextEncoder().encode(stableStringify({
+    resourceUrl: parsed.resource.url,
+    selectedRequirement: parsed.selectedRequirement,
+  }))))}`;
+}
+
 function decodePaymentRequired(paymentRequired: string | Record<string, unknown>): unknown {
   if (typeof paymentRequired !== "string") {
     return paymentRequired;
@@ -132,6 +266,104 @@ function decodePaymentRequired(paymentRequired: string | Record<string, unknown>
   return JSON.parse(json) as unknown;
 }
 
+const agentPayX402PaymentProofSchema = z.object({
+  x402Version: z.literal(2),
+  scheme: z.literal("agentpay-receipt"),
+  paymentIntentId: z.string().min(1),
+  paymentType: z.literal("X402_PAYMENT"),
+  payer: evmAddressSchema,
+  ownerAddress: evmAddressSchema,
+  resourceUrl: z.string().url(),
+  requirementHash: z.string().regex(/^0x[a-fA-F0-9]{64}$/),
+  network: z.string().min(1),
+  chainId: z.number().int().positive(),
+  asset: z.string().min(1),
+  payTo: evmAddressSchema,
+  amount: positiveIntegerStringSchema,
+  amountDecimal: z.string().min(1),
+  sourceTxHash: z.string().regex(/^0x[a-fA-F0-9]{64}$/),
+  destinationTxHash: z.string().regex(/^0x[a-fA-F0-9]{64}$/).optional(),
+  settlementTxHash: z.string().regex(/^0x[a-fA-F0-9]{64}$/),
+  completedAt: z.string().optional(),
+  paymentIdentifier: paymentIdentifierSchema.optional(),
+  extensions: z
+    .object({
+      "payment-identifier": z
+        .object({
+          info: z.object({
+            required: z.boolean(),
+            id: paymentIdentifierSchema,
+          }),
+        })
+        .optional(),
+    })
+    .optional(),
+});
+
+function validateCompletedX402Intent(parsed: ParsedX402PaymentRequired, paymentIntent: PaymentIntentRecord): void {
+  if (paymentIntent.status !== "COMPLETED") {
+    throw new Error(`Payment intent ${paymentIntent.id} must be COMPLETED before x402 proof can be generated.`);
+  }
+
+  if (paymentIntent.paymentType !== "X402_PAYMENT") {
+    throw new Error(`Payment intent ${paymentIntent.id} must be an X402_PAYMENT intent.`);
+  }
+
+  if (!paymentIntent.sourceTxHash) {
+    throw new Error(`Payment intent ${paymentIntent.id} is missing a source transaction hash.`);
+  }
+
+  const selected = parsed.selectedRequirement;
+  const matchesRequirement =
+    paymentIntent.destinationChainId === selected.chainId &&
+    paymentIntent.destinationTokenAddress.toLowerCase() === selected.asset.toLowerCase() &&
+    paymentIntent.destinationTokenSymbol === selected.tokenSymbol &&
+    paymentIntent.recipientAddress.toLowerCase() === selected.payTo.toLowerCase() &&
+    paymentIntent.amountOut === selected.amount;
+
+  if (!matchesRequirement) {
+    throw new Error(`Payment intent ${paymentIntent.id} does not match the x402 requirement.`);
+  }
+}
+
+function encodeBase64UrlJson(value: unknown): string {
+  return Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}
+
+function parsePaymentIdentifierExtension(
+  extensions: Record<string, unknown> | undefined,
+): ParsedX402PaymentRequired["extensions"] extends infer Extensions
+  ? Extensions extends { "payment-identifier"?: infer Extension }
+    ? Extension | undefined
+    : never
+  : never {
+  const extension = extensions?.[PAYMENT_IDENTIFIER];
+
+  if (extension === undefined) {
+    return undefined;
+  }
+
+  if (!extension || typeof extension !== "object") {
+    throw new Error("Unsupported x402 payment-identifier extension.");
+  }
+
+  const info = (extension as { info?: unknown }).info;
+
+  if (!info || typeof info !== "object" || typeof (info as { required?: unknown }).required !== "boolean") {
+    throw new Error("Unsupported x402 payment-identifier extension.");
+  }
+
+  return {
+    info: {
+      required: (info as { required: boolean }).required,
+    },
+  };
+}
+
+function createPaymentIdentifier(paymentIntentId: string): string {
+  return paymentIdentifierSchema.parse(paymentIntentId);
+}
+
 function toSupportedRequirement(requirement: z.infer<typeof x402PaymentRequirementSchema>):
   | ParsedX402PaymentRequired["selectedRequirement"]
   | null {
@@ -202,3 +434,19 @@ function createX402Purpose(resource: z.infer<typeof x402ResourceInfoSchema>): st
 
   return `x402 payment for ${details}`.slice(0, 280);
 }
+
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value as Record<string, unknown>)
+      .filter(([, entryValue]) => entryValue !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`)
+      .join(",")}}`;
+  }
+
+  return JSON.stringify(value);
+}