diff --git a/packages/walletkit/src/api/scripts/generate-json-schema.js b/packages/walletkit/src/api/scripts/generate-json-schema.js
index 92f56c87..a11f099c 100644
--- a/packages/walletkit/src/api/scripts/generate-json-schema.js
+++ b/packages/walletkit/src/api/scripts/generate-json-schema.js
@@ -1494,6 +1494,41 @@ function postProcessConstantFields(schema) {
     }
 }
 
+/**
+ * Post-process schema to convert pure $ref definitions (type aliases) into
+ * x-type-alias markers so openapi-generator will create a file and the
+ * template can emit a Swift typealias.
+ */
+/**
+ * Post-process schema to strip `default` values from properties.
+ * @default JSDoc is documentation-only and should not produce default values in generated code.
+ */
+function postProcessStripDefaults(schema) {
+    const definitions = schema.definitions || {};
+    for (const typeDef of Object.values(definitions)) {
+        if (!typeDef.properties) continue;
+        for (const propDef of Object.values(typeDef.properties)) {
+            delete propDef.default;
+        }
+    }
+}
+
+function postProcessTypeAliases(schema) {
+    const definitions = schema.definitions || {};
+
+    for (const [, typeDef] of Object.entries(definitions)) {
+        if (typeDef.$ref && !typeDef.type && !typeDef.properties && !typeDef.allOf && !typeDef['x-enum-case-name']) {
+            const targetName = typeNameFromRef(typeDef.$ref);
+
+            Object.keys(typeDef).forEach((k) => delete typeDef[k]);
+            typeDef.type = 'object';
+            typeDef.properties = { _alias: { type: 'string' } };
+            typeDef['x-type-alias'] = true;
+            typeDef['x-alias-target'] = targetName;
+        }
+    }
+}
+
 // ============================================================================
 // Main
 // ============================================================================
@@ -1546,6 +1581,12 @@ try {
     // Post-process: convert single-literal properties to constant fields
     postProcessConstantFields(schema);
 
+    // Post-process: strip @default values (documentation-only, not for codegen)
+    postProcessStripDefaults(schema);
+
+    // Post-process: convert pure $ref definitions (type aliases) to x-type-alias
+    postProcessTypeAliases(schema);
+
     fs.writeFileSync(outputPath, JSON.stringify(schema, null, 2));
 } catch (error) {
     console.error('Error:', error.message);
diff --git a/packages/walletkit/src/api/scripts/generate-openapi-spec.sh b/packages/walletkit/src/api/scripts/generate-openapi-spec.sh
index f07440a2..fa58484c 100755
--- a/packages/walletkit/src/api/scripts/generate-openapi-spec.sh
+++ b/packages/walletkit/src/api/scripts/generate-openapi-spec.sh
@@ -6,31 +6,24 @@ set -e  # Exit on error
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Configuration
-TYPESCRIPT_INPUT="$SCRIPT_DIR/../models"
+SRC_ROOT="$SCRIPT_DIR/../.."
 OUTPUT_FILE="$SCRIPT_DIR/generated/walletkit-openapi.json"
 TEMP_SCHEMA="$SCRIPT_DIR/generated/temp-schema.json"
 
-if [ -z "$TYPESCRIPT_INPUT" ]; then
-    echo "❌ Error: TypeScript input path is required"
-fi
+# Input glob: api/models + any models folders under defi
+TYPESCRIPT_INPUT="$SRC_ROOT/{api/models,defi/**/models}/**/*.ts"
 
 echo "🚀 Converting TypeScript to OpenAPI specification..."
 echo "📁 TypeScript input: $TYPESCRIPT_INPUT"
 echo "📄 Output file: $OUTPUT_FILE"
 echo ""
 
-# Step 1: Validate TypeScript input
-if [ ! -d "$TYPESCRIPT_INPUT" ] && [ ! -f "$TYPESCRIPT_INPUT" ]; then
-    echo "❌ Error: TypeScript input not found at '$TYPESCRIPT_INPUT'"
-    exit 1
-fi
-
-# Step 2: Ensure generated directory exists
+# Step 1: Ensure generated directory exists
 mkdir -p "$SCRIPT_DIR/generated"
 
-# Step 3: Generate JSON Schema using custom generator (with x-enum-varnames)
+# Step 2: Generate JSON Schema using custom generator (with x-enum-varnames)
 echo "📝 Step 1: Generating JSON Schema with enum member names..."
-node "$SCRIPT_DIR/generate-json-schema.js" "$TYPESCRIPT_INPUT/**/*.ts" "$TEMP_SCHEMA" || {
+node "$SCRIPT_DIR/generate-json-schema.js" "$TYPESCRIPT_INPUT" "$TEMP_SCHEMA" || {
     echo "❌ Failed to generate JSON Schema"
     exit 1
 }