From 7023c5fbec6e8bd6b1337b04d1aa70804449d008 Mon Sep 17 00:00:00 2001
From: Lokesh Chandra <lokeshchandra956@bitgo.com>
Date: Thu, 20 Nov 2025 13:34:15 +0530
Subject: [PATCH] docs(express): signTransactionV1 API definition

Ticket: WP-6950
---
 .../src/typedRoutes/api/v1/signTransaction.ts | 47 +++++++++++++------
 1 file changed, 33 insertions(+), 14 deletions(-)

diff --git a/modules/express/src/typedRoutes/api/v1/signTransaction.ts b/modules/express/src/typedRoutes/api/v1/signTransaction.ts
index 19b80c4866..a5cfd644b8 100644
--- a/modules/express/src/typedRoutes/api/v1/signTransaction.ts
+++ b/modules/express/src/typedRoutes/api/v1/signTransaction.ts
@@ -8,13 +8,11 @@ export const signTransactionRequestParams = {
 };
 
 export const signTransactionRequestBody = {
-  /** Serialized form of the transaction in hex */
+  /** Serialized unsigned transaction in hex format (required for regular signing, not used with psbt) */
   transactionHex: t.string,
-  /** array of unspent information, where each unspent is a chainPath 
-  and redeemScript with the same index as the inputs in the
-  transactionHex */
+  /** Array of unspent information matching transaction inputs - each contains chainPath and redeemScript (required for regular signing, not used with psbt) */
   unspents: t.array(t.any),
-  /** Keychain containing the xprv to sign with (either this or signingKey required) */
+  /** Keychain containing xprv for signing (required for PSBT signing, or for regular signing if signingKey not provided) */
   keychain: optional(
     t.intersection([
       t.type({
@@ -23,23 +21,44 @@ export const signTransactionRequestBody = {
       t.record(t.string, t.any),
     ])
   ),
-  /** For legacy safe wallets, the private key string (either this or keychain required) */
+  /** For legacy safe wallets, WIF private key (alternative to keychain for regular signing only, not used with psbt) */
   signingKey: optional(t.string),
-  /** extra verification of signatures (which are always verified server-side) (defaults to global config) */
+  /** Extra signature verification (defaults to global BitGo config, always verified server-side) */
   validate: optional(t.boolean),
-  /** PSBT (Partially Signed Bitcoin Transaction) in hex format for PSBT signing flow */
+  /** PSBT (Partially Signed Bitcoin Transaction) in hex format - when provided, uses PSBT signing flow instead of regular signing */
   psbt: optional(t.string),
-  /** Private key in WIF format for single-key fee address */
+  /** WIF private key for signing single-key fee address inputs (used when transaction has fee inputs from single-key addresses) */
   feeSingleKeyWIF: optional(t.string),
-  /** Enable Bitcoin Cash signing mode */
+  /** Enable Bitcoin Cash signing mode for BCH transactions */
   forceBCH: optional(t.boolean),
   /** Require at least two valid signatures for full local signing */
   fullLocalSigning: optional(t.boolean),
 };
 
 /**
- * signTransaction
- * Sign a previously created transaction with a keychain
+ * Sign a transaction with wallet's user key
+ *
+ * Signs a previously created unsigned transaction with the wallet's user key. This endpoint
+ * supports two signing flows: regular transaction signing and PSBT (Partially Signed Bitcoin
+ * Transaction) signing.
+ *
+ * **Regular Transaction Signing:**
+ * Required parameters:
+ * - transactionHex: The unsigned transaction in hex format
+ * - unspents: Array of unspent information (chainPath, redeemScript) matching transaction inputs
+ * - keychain.xprv OR signingKey: Private key for signing
+ *
+ * **PSBT Signing:**
+ * Required parameters:
+ * - psbt: The PSBT in hex format
+ * - keychain.xprv: Extended private key for HD signing
+ *
+ * **Response:**
+ * - Regular signing: Returns { tx: string } - signed transaction hex
+ * - PSBT signing: Returns { psbt: string } - signed PSBT hex
+ *
+ * **Note:** The validate parameter controls signature verification. If omitted, uses the
+ * global BitGo validation setting. Signature verification is always performed server-side.
  *
  * @operationId express.v1.wallet.signTransaction
  * @tag express
@@ -52,9 +71,9 @@ export const PostSignTransaction = httpRoute({
     body: signTransactionRequestBody,
   }),
   response: {
-    /** Successfully accepted wallet share */
+    /** Successfully signed transaction. Returns { tx: string } for regular signing or { psbt: string } for PSBT signing. */
     200: t.UnknownRecord,
-    /** Error response */
+    /** Error response (e.g., missing required parameters, invalid transaction hex, invalid keychain, signature verification failure) */
     400: BitgoExpressError,
   },
 });