@circle-fin/app-kit 1.15.3 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@circle-fin/app-kit",
-  "version": "1.15.3",
+  "version": "1.17.0",
   "description": "A one-stop Circle SDK solution for building stablecoin (e.g. USDC) applications, with bridging, swapping, and more on-chain operations",
   "keywords": [
     "circle",
@@ -36,12 +36,13 @@
   "module": "./index.mjs",
   "types": "./index.d.cts",
   "dependencies": {
-    "@circle-fin/onramp-kit": "1.0.2",
-    "@circle-fin/unified-balance-kit": "1.7.0",
-    "@circle-fin/provider-gateway-v1": "1.5.0",
-    "@circle-fin/earn-kit": "1.8.0",
-    "@circle-fin/bridge-kit": "1.15.1",
-    "@circle-fin/swap-kit": "1.7.0",
+    "@circle-fin/onramp-kit": "1.0.4",
+    "@circle-fin/unified-balance-kit": "1.8.1",
+    "@circle-fin/provider-gateway-v1": "1.5.2",
+    "@circle-fin/earn-kit": "1.9.0",
+    "@circle-fin/borrow-kit": "1.1.0",
+    "@circle-fin/bridge-kit": "1.15.3",
+    "@circle-fin/swap-kit": "1.8.0",
     "@coral-xyz/anchor": "^0.31.1",
     "@noble/curves": "1.4.2",
     "bn.js": "^5.2.3",
@@ -117,6 +118,14 @@
       "import": "./earn.mjs",
       "require": "./earn.cjs"
     },
+    "./borrow": {
+      "types": {
+        "import": "./borrow.d.mts",
+        "require": "./borrow.d.cts"
+      },
+      "import": "./borrow.mjs",
+      "require": "./borrow.cjs"
+    },
     "./estimateSwap": {
       "types": {
         "import": "./estimateSwap.d.mts",
@@ -152,6 +161,7 @@
     "estimateSwap.*",
     "unifiedBalance.*",
     "earn.*",
+    "borrow.*",
     "index.*",
     "server.*",
     "README.md",

package/server.cjs

@@ -639,6 +639,34 @@ class KitError extends Error {
     }
 };
 
+/**
+ * Render an object value for an error message without letting the rendering
+ * itself throw.
+ *
+ * `JSON.stringify` rejects `BigInt` and circular structures, and a rejected
+ * value is exactly the kind of thing a validation error is built from: an
+ * on-chain read or a receipt log carries `bigint` fields, so serializing one
+ * naively replaces the intended error with a `TypeError`.
+ *
+ * @param value - The value to render.
+ * @returns A JSON string with `bigint` fields stringified, or
+ *   `'[unserializable object]'` if serialization still fails.
+ * @throws Never; serialization failures are caught and rendered as a fallback string.
+ * @example
+ * ```typescript
+ * import { describeObjectValue } from '@core/errors'
+ *
+ * describeObjectValue({ amount: 1n })
+ * // '{"amount":"1"}'
+ * ```
+ */ function describeObjectValue(value) {
+    try {
+        return JSON.stringify(value, (_key, entry)=>typeof entry === 'bigint' ? entry.toString() : entry);
+    } catch  {
+        return '[unserializable object]';
+    }
+}
+
 /**
  * Creates error for general validation failure.
  *
@@ -661,7 +689,7 @@ class KitError extends Error {
  * // Message: "Validation failed for 'chainId': 999 - Unsupported chain ID"
  *
  * throw createValidationFailedError('config', { invalid: true }, 'Missing required properties')
- * // Message: "Validation failed for 'config': [object Object] - Missing required properties"
+ * // Message: "Validation failed for 'config': {"invalid":true} - Missing required properties"
  * ```
  */ function createValidationFailedError(field, value, reason) {
     // Convert value to string for display, handling different types appropriately
@@ -669,7 +697,7 @@ class KitError extends Error {
     if (typeof value === 'string') {
         valueString = `'${value}'`;
     } else if (typeof value === 'object' && value !== null) {
-        valueString = JSON.stringify(value);
+        valueString = describeObjectValue(value);
     } else {
         valueString = String(value);
     }
@@ -1190,6 +1218,8 @@ var SwapChain;
     SwapChain["HyperEVM"] = "HyperEVM";
     SwapChain["Monad"] = "Monad";
     SwapChain["Arc"] = "Arc";
+    SwapChain["Cronos"] = "Cronos";
+    SwapChain["Morph"] = "Morph";
     // Testnet chains with swap support
     SwapChain["Arc_Testnet"] = "Arc_Testnet";
 })(SwapChain || (SwapChain = {}));
@@ -1321,6 +1351,11 @@ var EarnChain;
     "Arc",
     "Arc_Testnet"
 ];
+var BorrowChain;
+(function(BorrowChain) {
+    BorrowChain["Arc"] = "Arc";
+    BorrowChain["Arc_Testnet"] = "Arc_Testnet";
+})(BorrowChain || (BorrowChain = {}));
 
 /**
  * Helper function to define a chain with proper TypeScript typing.
@@ -1663,6 +1698,29 @@ var EarnChain;
  * on EVM-compatible testnet chains. Use this address for testnet adapter
  * integrations (e.g., Arc Testnet).
  */ const ADAPTER_CONTRACT_EVM_TESTNET = '0xBBD70b01a1CAbc96d5b7b129Ae1AAabdf50dd40b';
+/**
+ * The sender-preserving batching contract on Arc (`Multicall3From`).
+ *
+ * This predeploy batches calls like the ubiquitous Multicall3, but routes each
+ * subcall through Arc's `CallFrom` precompile
+ * (`0x1800000000000000000000000000000000000003`), which executes on behalf of
+ * the transaction's original sender. Every target therefore sees the calling
+ * EOA as `msg.sender`, which is what makes a plain, un-upgraded EOA capable of
+ * an atomic batch on Arc.
+ *
+ * Deployed at the same address on Arc Testnet and Arc Mainnet.
+ *
+ * @see https://docs.arc.io/arc/concepts/batched-transactions
+ */ const BATCHER_CONTRACT_ARC_TESTNET = '0x522fAf9A91c41c443c66765030741e4AaCe147D0';
+/**
+ * The sender-preserving batching contract on Arc Mainnet (`Multicall3From`).
+ *
+ * See {@link BATCHER_CONTRACT_ARC_TESTNET} for how this contract works.
+ * Requires Arc's Zero7 hardfork, which activates the `CallFrom` precompile
+ * this contract depends on.
+ *
+ * @see https://docs.arc.io/arc/concepts/batched-transactions
+ */ const BATCHER_CONTRACT_ARC_MAINNET = '0x522fAf9A91c41c443c66765030741e4AaCe147D0';
 /**
  * The GatewayWallet contract address for EVM mainnet networks.
  *
@@ -1802,7 +1860,10 @@ var EarnChain;
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_MAINNET,
-        adapter: ADAPTER_CONTRACT_EVM_MAINNET
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET,
+        // Arc is the only chain with a sender-preserving batcher, because it
+        // takes a precompile rather than an ordinary contract to build one.
+        senderPreservingBatcher: BATCHER_CONTRACT_ARC_MAINNET
     },
     gateway: {
         domain: 26,
@@ -1873,7 +1934,10 @@ var EarnChain;
     },
     kitContracts: {
         bridge: BRIDGE_CONTRACT_EVM_TESTNET,
-        adapter: ADAPTER_CONTRACT_EVM_TESTNET
+        adapter: ADAPTER_CONTRACT_EVM_TESTNET,
+        // Arc is the only chain with a sender-preserving batcher, because it
+        // takes a precompile rather than an ordinary contract to build one.
+        senderPreservingBatcher: BATCHER_CONTRACT_ARC_TESTNET
     },
     gateway: {
         domain: 26,
@@ -2488,7 +2552,8 @@ var EarnChain;
         }
     },
     kitContracts: {
-        bridge: BRIDGE_CONTRACT_EVM_MAINNET
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET
     }
 });
 
@@ -3357,7 +3422,8 @@ var EarnChain;
         }
     },
     kitContracts: {
-        bridge: BRIDGE_CONTRACT_EVM_MAINNET
+        bridge: BRIDGE_CONTRACT_EVM_MAINNET,
+        adapter: ADAPTER_CONTRACT_EVM_MAINNET
     }
 });
 
@@ -5291,7 +5357,8 @@ var EarnChain;
     cctpx: zod.z.any().optional(),
     kitContracts: zod.z.object({
         bridge: zod.z.string().optional(),
-        adapter: zod.z.string().optional()
+        adapter: zod.z.string().optional(),
+        senderPreservingBatcher: zod.z.string().optional()
     }).optional(),
     gateway: gatewayConfigSchema.optional()
 });
@@ -5402,8 +5469,8 @@ var EarnChain;
  * Zod schema for validating swap-specific chain identifiers.
  *
  * Validates chains based on:
- * - CCTPv2 support (adapter contract deployed)
- * - Mainnet only (no testnets)
+ * - Membership in the SwapChain enum
+ * - Mainnet or explicitly allowlisted testnet
  * - At least one supported token available
  *
  */ zod.z.union([
@@ -5487,6 +5554,38 @@ var EarnChain;
             message: `"${chain.chain}" is not a supported earn chain. ` + `Supported chains: ${Object.values(EarnChain).join(', ')}`
         }))
 ]);
+/**
+ * Zod schema for validating Borrow-specific chain identifiers.
+ *
+ * Validate that the provided chain is supported for Borrow Kit's loan
+ * operations. Unlike {@link earnChainIdentifierSchema}, this includes Arc
+ * mainnet as well as Arc Testnet.
+ *
+ * Accept a BorrowChain enum value, a matching string literal, or a
+ * ChainDefinition for a supported chain.
+ *
+ * @example
+ * ```typescript
+ * import { borrowChainIdentifierSchema } from '@core/chains'
+ * import { Arc, BorrowChain } from '@core/chains'
+ *
+ * // Valid
+ * borrowChainIdentifierSchema.parse(BorrowChain.Arc)
+ * borrowChainIdentifierSchema.parse('Arc')
+ * borrowChainIdentifierSchema.parse(Arc)
+ *
+ * // Invalid (throws ZodError)
+ * borrowChainIdentifierSchema.parse('Solana')
+ * ```
+ */ zod.z.union([
+    zod.z.string().refine((val)=>val in BorrowChain, (val)=>({
+            message: `"${val}" is not a supported borrow chain. ` + `Supported chains: ${Object.values(BorrowChain).join(', ')}`
+        })),
+    zod.z.nativeEnum(BorrowChain),
+    chainDefinitionSchema.refine((chain)=>chain.chain in BorrowChain, (chain)=>({
+            message: `"${chain.chain}" is not a supported borrow chain. ` + `Supported chains: ${Object.values(BorrowChain).join(', ')}`
+        }))
+]);
 // Widened views so `.includes()` accepts arbitrary strings under strict TS.
 const EARN_BRIDGE_SOURCE_CHAIN_VALUES = EARN_BRIDGE_SOURCE_BLOCKCHAINS;
 const EARN_BRIDGE_DESTINATION_CHAIN_VALUES = EARN_BRIDGE_DESTINATION_BLOCKCHAINS;
@@ -6108,11 +6207,13 @@ const swapTokenEnumSchema = zod.z.enum([
         [Blockchain.Arbitrum]: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9',
         [Blockchain.Avalanche]: '0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7',
         [Blockchain.Celo]: '0x48065fbBE25f71C9282ddf5e1cD6D6A887483D5e',
+        [Blockchain.Cronos]: '0x66e428c3f67a68878562e79A0234c1F83c208770',
         [Blockchain.Ethereum]: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
         [Blockchain.HyperEVM]: '0xb8ce59fc3717ada4c02eadf9682a9e934f625ebb',
         [Blockchain.Ink]: '0x0200C29006150606B650577BBE7B6248F58470c1',
         [Blockchain.Linea]: '0xA219439258ca9da29E9Cc4cE5596924745e12B93',
         [Blockchain.Monad]: '0xe7cd86e13AC4309349F30B3435a9d337750fC82D',
+        [Blockchain.Morph]: '0xe7cd86e13AC4309349F30B3435a9d337750fC82D',
         [Blockchain.NEAR]: 'usdt.tether-token.near',
         [Blockchain.Optimism]: '0x94b008aA00579c1307B0EF2c499aD98a8ce58e58',
         [Blockchain.Polkadot_Asset_Hub]: '1984',
@@ -6171,6 +6272,7 @@ const swapTokenEnumSchema = zod.z.enum([
         [Blockchain.Arbitrum]: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1',
         [Blockchain.Avalanche]: '0xd586E7F844cEa2F87f50152665BCbc2C279D8d70',
         [Blockchain.Base]: '0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb',
+        [Blockchain.Cronos]: '0xF2001B145b43032AAF5Ee2884e456CCd805F677D',
         [Blockchain.Ethereum]: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
         [Blockchain.Linea]: '0x4AF15ec2A0BD43Db75dd04E62FAA3B8EF36b00d5',
         [Blockchain.Optimism]: '0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1',
@@ -6233,7 +6335,9 @@ const swapTokenEnumSchema = zod.z.enum([
         [Blockchain.Arbitrum]: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1',
         [Blockchain.Avalanche]: '0x49D5c2BdFfac6CE2BFdB6640F4F80f226bc10bAB',
         [Blockchain.Base]: '0x4200000000000000000000000000000000000006',
+        [Blockchain.Cronos]: '0xe44Fd7fCb2b1581822D0c862B68222998a0c299a',
         [Blockchain.Ethereum]: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
+        [Blockchain.Morph]: '0x5300000000000000000000000000000000000011',
         [Blockchain.Optimism]: '0x4200000000000000000000000000000000000006',
         [Blockchain.Polygon]: '0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619',
         [Blockchain.Solana]: '7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs'
@@ -6252,6 +6356,7 @@ const swapTokenEnumSchema = zod.z.enum([
     locators: {
         [Blockchain.Ethereum]: '0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599',
         [Blockchain.Arbitrum]: '0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f',
+        [Blockchain.Cronos]: '0x062E66477Faf219F25D27dCED647BF57C3107d52',
         [Blockchain.Avalanche]: '0x50b7545627a5162F82A992c33b87aDc75187B218'
     }
 };
@@ -8650,7 +8755,7 @@ const swapTokenEnumSchema = zod.z.enum([
     return kit;
 }
 
-var version = "1.0.2";
+var version = "1.0.4";
 var pkg = {
 	version: version};
 
@@ -9286,7 +9391,7 @@ function isAbortLikeError(err) {
     currency: zod.z.string().min(1).optional(),
     email: zod.z.string().email().optional(),
     assets: onrampAssetSelectionSchema.optional(),
-    metadata: zod.z.record(zod.z.string(), zod.z.unknown()).optional()
+    metadata: zod.z.record(zod.z.string(), zod.z.string()).optional()
 });
 
 /**
@@ -9448,7 +9553,7 @@ function isAbortLikeError(err) {
             const widgetUrl = mergeAssetParams(existingWidgetUrl, composedWidgetUrl, assetParams);
             const traceId = typeof session['traceId'] === 'string' ? session['traceId'] : ctx.invocation.traceId;
             // Outbound allow-list. We deliberately rebuild the result from the
-            // exact fields the client kit consumes rather than spreading
+            // exact fields the host and client kit consume rather than spreading
             // `...session`. Inbound parsing stays schema-free for forward-compat
             // (an additive upstream field must never break minting), but the
             // server→browser hop is a trust boundary: any internal identifier,
@@ -9467,6 +9572,11 @@ function isAbortLikeError(err) {
             if (typeof session['expiresAt'] === 'string') {
                 normalised['expiresAt'] = session['expiresAt'];
             }
+            // From the response only. No fallback to `params.metadata`.
+            const metadata = readMetadataEcho(session['metadata']);
+            if (metadata !== undefined) {
+                normalised['metadata'] = metadata;
+            }
             if (widgetUrl === undefined) {
                 // `widgetUrl` is required on `MintedOnrampSession` (guaranteed
                 // present). If neither the API returned one nor a `sessionToken`
@@ -9503,6 +9613,17 @@ function isAbortLikeError(err) {
     }
     return url.toString();
 }
+/**
+ * Copy a plain-object, string-valued `metadata` echo, or drop it whole.
+ *
+ * @internal
+ */ function readMetadataEcho(value) {
+    if (value === null || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
+        return undefined;
+    }
+    const entries = Object.entries(value);
+    return entries.every(([, entry])=>typeof entry === 'string') ? Object.fromEntries(entries) : undefined;
+}
 /**
  * Translate the SDK parameter shape into the wallets-api request body.
  *

package/server.d.cts

@@ -1801,6 +1801,8 @@ interface KitEventSubscription<M extends EventMap = KitEventMap> {
  *   re-mint.
  * - `traceId` — the trace id the server stamped when minting. Echoed
  *   back so the client can tag widget events with the same id.
+ * - `metadata`: string map echoed on the create response, when the API
+ *   sends one. Forwarded to the browser with the rest of the session.
  */
 interface OnrampSession {
     /**
@@ -1854,6 +1856,18 @@ interface OnrampSession {
      * id.
      */
     readonly traceId?: string;
+    /**
+     * Request `metadata` as the Onramp API echoed it on the create response.
+     *
+     * @remarks
+     * Present only for a well-formed echo, never copied from the request
+     * params, so absence means the API did not echo it. Returned once: not
+     * sealed into the session token or delivered on later events. A host
+     * that forwards the session to the browser (including via
+     * `createSessionRouteHandler`) also forwards this field, so do not put
+     * server-only values in it.
+     */
+    readonly metadata?: Readonly<Record<string, string>>;
     /**
      * Index signature keeping the type tolerant of additive fields.
      *
@@ -1898,9 +1912,8 @@ interface MintedOnrampSession extends OnrampSession {
  * contract.
  *
  * Validation is intentionally conservative: only the fields the kit
- * actually consumes (or rejects on shape grounds) are checked. Free-
- * form fields like `metadata` pass through so wallets-api can layer
- * its own validation on top without the SDK lagging behind.
+ * actually consumes (or rejects on shape grounds) are checked.
+ * `metadata` is a string map. The Onramp API owns its limits.
  *
  * @packageDocumentation
  */
@@ -1943,7 +1956,7 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
             chain: string;
         }[] | undefined;
     }>>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     appUserId: string;
     destinationAddress: string;
@@ -1959,7 +1972,7 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
             chain: string;
         }[] | undefined;
     } | undefined;
-    metadata?: Record<string, unknown> | undefined;
+    metadata?: Record<string, string> | undefined;
 }, {
     appUserId: string;
     destinationAddress: string;
@@ -1975,7 +1988,7 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
             chain: string;
         }[] | undefined;
     } | undefined;
-    metadata?: Record<string, unknown> | undefined;
+    metadata?: Record<string, string> | undefined;
 }>;
 /**
  * The wire-format request body accepted by the onramp `createSession`
@@ -1999,8 +2012,11 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
  * - `assets`: optional host-app scoping for the asset selector (which
  *   token/chain pairs the widget offers). See {@link OnrampAssetSelection}.
  *   Baked into the launch URL at mint time; never forwarded to wallets-api.
- * - `metadata`: free-form passthrough — useful for re-stitching the
- *   session back to the host's order ledger.
+ * - `metadata`: optional string map. The Onramp API rejects more than 20
+ *   keys, keys over 64 characters, values over 1024 characters, and
+ *   control characters. It is echoed once on the create response (see
+ *   {@link OnrampSession.metadata}) and is not delivered on later widget
+ *   events, so use `appUserId` to correlate the user.
  *
  * Note: the embedding-domain allowlist entry (`referrerDomain`) is **not**
  * part of this request. It is a server-only concern configured on
@@ -2030,8 +2046,11 @@ type OnrampSessionRequest = z.infer<typeof onrampSessionRequestSchema>;
  *   wallets-api. Pass to pre-select a chain in the widget.
  * - `amount`, `currency`: optional pre-fills.
  * - `email`: optional KYC routing hint.
- * - `metadata`: free-form passthrough — useful for re-stitching the
- *   session back to the host's order ledger.
+ * - `metadata`: optional string map. The Onramp API rejects more than 20
+ *   keys, keys over 64 characters, values over 1024 characters, and
+ *   control characters. It is echoed once on the create response (see
+ *   {@link OnrampSession.metadata}) and is not delivered on later widget
+ *   events, so use `appUserId` to correlate the user.
  */
 type CreateSessionParams = OnrampSessionRequest;
 /**

package/server.d.mts

@@ -1801,6 +1801,8 @@ interface KitEventSubscription<M extends EventMap = KitEventMap> {
  *   re-mint.
  * - `traceId` — the trace id the server stamped when minting. Echoed
  *   back so the client can tag widget events with the same id.
+ * - `metadata`: string map echoed on the create response, when the API
+ *   sends one. Forwarded to the browser with the rest of the session.
  */
 interface OnrampSession {
     /**
@@ -1854,6 +1856,18 @@ interface OnrampSession {
      * id.
      */
     readonly traceId?: string;
+    /**
+     * Request `metadata` as the Onramp API echoed it on the create response.
+     *
+     * @remarks
+     * Present only for a well-formed echo, never copied from the request
+     * params, so absence means the API did not echo it. Returned once: not
+     * sealed into the session token or delivered on later events. A host
+     * that forwards the session to the browser (including via
+     * `createSessionRouteHandler`) also forwards this field, so do not put
+     * server-only values in it.
+     */
+    readonly metadata?: Readonly<Record<string, string>>;
     /**
      * Index signature keeping the type tolerant of additive fields.
      *
@@ -1898,9 +1912,8 @@ interface MintedOnrampSession extends OnrampSession {
  * contract.
  *
  * Validation is intentionally conservative: only the fields the kit
- * actually consumes (or rejects on shape grounds) are checked. Free-
- * form fields like `metadata` pass through so wallets-api can layer
- * its own validation on top without the SDK lagging behind.
+ * actually consumes (or rejects on shape grounds) are checked.
+ * `metadata` is a string map. The Onramp API owns its limits.
  *
  * @packageDocumentation
  */
@@ -1943,7 +1956,7 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
             chain: string;
         }[] | undefined;
     }>>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     appUserId: string;
     destinationAddress: string;
@@ -1959,7 +1972,7 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
             chain: string;
         }[] | undefined;
     } | undefined;
-    metadata?: Record<string, unknown> | undefined;
+    metadata?: Record<string, string> | undefined;
 }, {
     appUserId: string;
     destinationAddress: string;
@@ -1975,7 +1988,7 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
             chain: string;
         }[] | undefined;
     } | undefined;
-    metadata?: Record<string, unknown> | undefined;
+    metadata?: Record<string, string> | undefined;
 }>;
 /**
  * The wire-format request body accepted by the onramp `createSession`
@@ -1999,8 +2012,11 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
  * - `assets`: optional host-app scoping for the asset selector (which
  *   token/chain pairs the widget offers). See {@link OnrampAssetSelection}.
  *   Baked into the launch URL at mint time; never forwarded to wallets-api.
- * - `metadata`: free-form passthrough — useful for re-stitching the
- *   session back to the host's order ledger.
+ * - `metadata`: optional string map. The Onramp API rejects more than 20
+ *   keys, keys over 64 characters, values over 1024 characters, and
+ *   control characters. It is echoed once on the create response (see
+ *   {@link OnrampSession.metadata}) and is not delivered on later widget
+ *   events, so use `appUserId` to correlate the user.
  *
  * Note: the embedding-domain allowlist entry (`referrerDomain`) is **not**
  * part of this request. It is a server-only concern configured on
@@ -2030,8 +2046,11 @@ type OnrampSessionRequest = z.infer<typeof onrampSessionRequestSchema>;
  *   wallets-api. Pass to pre-select a chain in the widget.
  * - `amount`, `currency`: optional pre-fills.
  * - `email`: optional KYC routing hint.
- * - `metadata`: free-form passthrough — useful for re-stitching the
- *   session back to the host's order ledger.
+ * - `metadata`: optional string map. The Onramp API rejects more than 20
+ *   keys, keys over 64 characters, values over 1024 characters, and
+ *   control characters. It is echoed once on the create response (see
+ *   {@link OnrampSession.metadata}) and is not delivered on later widget
+ *   events, so use `appUserId` to correlate the user.
  */
 type CreateSessionParams = OnrampSessionRequest;
 /**

package/server.d.ts

@@ -1801,6 +1801,8 @@ interface KitEventSubscription<M extends EventMap = KitEventMap> {
  *   re-mint.
  * - `traceId` — the trace id the server stamped when minting. Echoed
  *   back so the client can tag widget events with the same id.
+ * - `metadata`: string map echoed on the create response, when the API
+ *   sends one. Forwarded to the browser with the rest of the session.
  */
 interface OnrampSession {
     /**
@@ -1854,6 +1856,18 @@ interface OnrampSession {
      * id.
      */
     readonly traceId?: string;
+    /**
+     * Request `metadata` as the Onramp API echoed it on the create response.
+     *
+     * @remarks
+     * Present only for a well-formed echo, never copied from the request
+     * params, so absence means the API did not echo it. Returned once: not
+     * sealed into the session token or delivered on later events. A host
+     * that forwards the session to the browser (including via
+     * `createSessionRouteHandler`) also forwards this field, so do not put
+     * server-only values in it.
+     */
+    readonly metadata?: Readonly<Record<string, string>>;
     /**
      * Index signature keeping the type tolerant of additive fields.
      *
@@ -1898,9 +1912,8 @@ interface MintedOnrampSession extends OnrampSession {
  * contract.
  *
  * Validation is intentionally conservative: only the fields the kit
- * actually consumes (or rejects on shape grounds) are checked. Free-
- * form fields like `metadata` pass through so wallets-api can layer
- * its own validation on top without the SDK lagging behind.
+ * actually consumes (or rejects on shape grounds) are checked.
+ * `metadata` is a string map. The Onramp API owns its limits.
  *
  * @packageDocumentation
  */
@@ -1943,7 +1956,7 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
             chain: string;
         }[] | undefined;
     }>>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     appUserId: string;
     destinationAddress: string;
@@ -1959,7 +1972,7 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
             chain: string;
         }[] | undefined;
     } | undefined;
-    metadata?: Record<string, unknown> | undefined;
+    metadata?: Record<string, string> | undefined;
 }, {
     appUserId: string;
     destinationAddress: string;
@@ -1975,7 +1988,7 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
             chain: string;
         }[] | undefined;
     } | undefined;
-    metadata?: Record<string, unknown> | undefined;
+    metadata?: Record<string, string> | undefined;
 }>;
 /**
  * The wire-format request body accepted by the onramp `createSession`
@@ -1999,8 +2012,11 @@ declare const onrampSessionRequestSchema: z.ZodObject<{
  * - `assets`: optional host-app scoping for the asset selector (which
  *   token/chain pairs the widget offers). See {@link OnrampAssetSelection}.
  *   Baked into the launch URL at mint time; never forwarded to wallets-api.
- * - `metadata`: free-form passthrough — useful for re-stitching the
- *   session back to the host's order ledger.
+ * - `metadata`: optional string map. The Onramp API rejects more than 20
+ *   keys, keys over 64 characters, values over 1024 characters, and
+ *   control characters. It is echoed once on the create response (see
+ *   {@link OnrampSession.metadata}) and is not delivered on later widget
+ *   events, so use `appUserId` to correlate the user.
  *
  * Note: the embedding-domain allowlist entry (`referrerDomain`) is **not**
  * part of this request. It is a server-only concern configured on
@@ -2030,8 +2046,11 @@ type OnrampSessionRequest = z.infer<typeof onrampSessionRequestSchema>;
  *   wallets-api. Pass to pre-select a chain in the widget.
  * - `amount`, `currency`: optional pre-fills.
  * - `email`: optional KYC routing hint.
- * - `metadata`: free-form passthrough — useful for re-stitching the
- *   session back to the host's order ledger.
+ * - `metadata`: optional string map. The Onramp API rejects more than 20
+ *   keys, keys over 64 characters, values over 1024 characters, and
+ *   control characters. It is echoed once on the create response (see
+ *   {@link OnrampSession.metadata}) and is not delivered on later widget
+ *   events, so use `appUserId` to correlate the user.
  */
 type CreateSessionParams = OnrampSessionRequest;
 /**