From b6d4cc6aed1abc41eef4f95d11fda6c9352593bc Mon Sep 17 00:00:00 2001
From: tfibtcagent <tfi.reubs@gmail.com>
Date: Wed, 1 Apr 2026 16:39:35 +0000
Subject: [PATCH] fix(x402): classify transaction_held as TRANSACTION_PENDING
 (closes #93)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The relay's /settle endpoint returns errorReason: "transaction_held" when
a sender has a nonce gap and the relay queues the tx rather than dispatching
it. This error reason was not matched by classifyPaymentError, causing it to
fall through to the catch-all UNEXPECTED_SETTLE_ERROR (500 UNKNOWN_ERROR).

Add a transaction_held case that maps to TRANSACTION_PENDING with a 30s
retryAfter — longer than the 10s for transaction_pending since resolving
a nonce gap takes more time. The client receives 402 with a clear retry
signal rather than a confusing 500.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/middleware/x402.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/middleware/x402.ts b/src/middleware/x402.ts
index c83087f..9dedf02 100644
--- a/src/middleware/x402.ts
+++ b/src/middleware/x402.ts
@@ -152,6 +152,13 @@ function classifyPaymentError(error: unknown, settleResult?: Partial<SettlementR
     return { code: X402_ERROR_CODES.TRANSACTION_PENDING, message: "Transaction pending in settlement relay, please retry", httpStatus: 402, retryAfter: 10 };
   }
 
+  // Relay nonce queue: transaction held due to a sender nonce gap. The relay accepted
+  // the tx but can't dispatch it until the gap is filled. Treat as retryable TRANSACTION_PENDING
+  // with a longer backoff — the gap may take 30+ seconds to resolve.
+  if (combined.includes("transaction_held") || combined.includes("transaction held")) {
+    return { code: X402_ERROR_CODES.TRANSACTION_PENDING, message: "Transaction held in relay nonce queue, please retry", httpStatus: 402, retryAfter: 30 };
+  }
+
   if (combined.includes("sender_mismatch") || combined.includes("sender mismatch")) {
     return { code: X402_ERROR_CODES.SENDER_MISMATCH, message: "Payment sender does not match expected address", httpStatus: 400 };
   }