fix: dual-scheme UX — dynamic auth hints and body descriptions

- auth_hint now lists all active payment schemes instead of hardcoding L402
- L402 body includes scheme='L402' + description='Buy credits'
- IETF Payment body includes scheme='Payment' + description='Pay per request'
- Single-rail deployments get a string hint; multi-rail get an array

Author: TheCryptoDonkey

src/core/ietf-payment.ts

@@ -225,6 +225,8 @@ export function createIETFPaymentRail(config: IETFPaymentRailConfig): PaymentRai
         },
         body: {
           ietf_payment: {
+            scheme: 'Payment',
+            description: 'Pay per request (IETF standard, stateless)',
             method: 'lightning',
             intent: 'charge',
             payment_hash: invoice.paymentHash,

src/core/l402-rail.ts

@@ -52,6 +52,8 @@ export function createL402Rail(config: L402RailConfig): PaymentRail {
         },
         body: {
           l402: {
+            scheme: 'L402',
+            description: 'Buy credits \u2014 pay once, reuse for multiple requests',
             invoice: bolt11,
             macaroon,
             payment_hash: paymentHash,

src/core/toll-booth.test.ts

@@ -829,7 +829,7 @@ describe('agent-friendly 402 body', () => {
       description: 'Network intelligence and channel suggestions',
     })
     expect(body.auth_hint).toBe(
-      'Pay the invoice, then send header \u2014 Authorization: L402 <macaroon>:<preimage>',
+      'L402: Pay the invoice, then send \u2014 Authorization: L402 <macaroon>:<preimage>',
     )
   })
 
@@ -844,7 +844,7 @@ describe('agent-friendly 402 body', () => {
     const body = result.body as Record<string, unknown>
     expect(body.booth).toEqual({ name: 'Simple API' })
     expect(body.auth_hint).toBe(
-      'Pay the invoice, then send header \u2014 Authorization: L402 <macaroon>:<preimage>',
+      'L402: Pay the invoice, then send \u2014 Authorization: L402 <macaroon>:<preimage>',
     )
   })
 

src/core/toll-booth.ts

@@ -138,13 +138,28 @@ export function createTollBooth(config: TollBoothCoreConfig): TollBoothEngine {
         }
 
         // Agent-friendly service metadata (only when serviceName is configured).
-        // auth_hint is L402-specific; x402/xcashu have different auth mechanisms.
         if (config.serviceName) {
           challengeBody.booth = {
             name: config.serviceName,
             ...(config.description && { description: config.description }),
           }
-          challengeBody.auth_hint = 'Pay the invoice, then send header \u2014 Authorization: L402 <macaroon>:<preimage>'
+
+          // Build auth hints based on active rails
+          const activeTypes = rails.filter(r => !r.canChallenge || r.canChallenge(normalisedPrice)).map(r => r.type)
+          const hints: string[] = []
+          if (activeTypes.includes('l402')) {
+            hints.push('L402: Pay the invoice, then send \u2014 Authorization: L402 <macaroon>:<preimage>')
+          }
+          if (activeTypes.includes('ietf-payment')) {
+            hints.push('IETF Payment: Pay the invoice, then send \u2014 Authorization: Payment <base64url credential>')
+          }
+          if (activeTypes.includes('x402')) {
+            hints.push('x402: Sign the payment, then send \u2014 PAYMENT-SIGNATURE header')
+          }
+          if (activeTypes.includes('xcashu')) {
+            hints.push('Cashu: Send token via \u2014 X-Cashu header')
+          }
+          challengeBody.auth_hint = hints.length === 1 ? hints[0] : hints
         }
 
         // Store invoice data from L402 rail if present