fix: align relay payment polling contract with tx-schemas (#95)

* fix: align relay payment polling contract with tx-schemas

* test: lock payment contract parity surfaces

* chore: align x402-api payment contract verification with released schemas

* fix: address payment contract review feedback

* fix: document test-only export, clarify dual logging, annotate type cast

- Add comment on getRetryDecisionContext explaining it's used by test
  utilities, not production middleware (not dead code)
- Add comment on dual payment.poll/payment.retry_decision emission
  explaining dashboard vs alerting consumer split
- Add comment on `as unknown` cast in estimateInputTokens explaining
  OpenRouter SDK type narrowing mismatch

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: whoabuddy

README.md

@@ -75,6 +75,21 @@ bun run tests/_run_all_tests.ts --category=hashing
 bun run tests/_run_all_tests.ts --filter=sha256 --all-tokens
 ```
 
+### Rollout Check
+
+For the immediate-pay-per-call stabilization path, run a focused staging or production check against a cheap paid endpoint:
+
+```bash
+export X402_WORKER_URL=https://x402.aibtc.dev
+bun run tests/_run_all_tests.ts --filter=sha256 --token=STX --retries=2 --verbose
+```
+
+On any retryable 402 during this check, confirm the body stays on canonical caller-facing semantics:
+- `status` never returns `submitted`
+- `paymentId` is present before retrying the same payment
+- `terminalReason` is the normalized terminal signal when present
+- `checkStatusUrl` is treated as additive when present
+
 ### Test Modes
 
 | Mode | Description |

package-lock.json

@@ -28,6 +28,7 @@
     "wrangler": "^4.75.0"
   },
   "dependencies": {
+    "@aibtc/tx-schemas": "^0.3.0",
     "@stacks/encryption": "^7.3.1",
     "@stacks/network": "^7.3.1",
     "@stacks/transactions": "^7.3.1",

package.json

@@ -16,6 +16,7 @@
 
 import { Hono } from "hono";
 import type { Env, AppVariables } from "../types";
+import { PAYMENT_PUBLIC_LIFECYCLE } from "../utils/payment-contract";
 
 // =============================================================================
 // Content Definitions
@@ -41,6 +42,12 @@ signs a Stacks transaction and retries with the payment signature.
 
 This API supports x402 v2 (Coinbase-compatible) with Stacks blockchain payments.
 
+Canonical public payment lifecycle:
+- \`${PAYMENT_PUBLIC_LIFECYCLE}\`
+- \`submitted\` is never caller-facing
+- relay-owned \`paymentId\` is the stable in-flight identity
+- this service keeps immediate pay-per-call behavior during rollout, but any surfaced payment status follows the canonical lifecycle and may include \`checkStatusUrl\`
+
 ## Pricing Tiers
 
 | Tier     | Cost          | Endpoints                                    |
@@ -184,19 +191,43 @@ Legacy headers (still accepted for backward compatibility):
 - \`X-PAYMENT\` (replaces payment-signature)
 - \`X-PAYMENT-RESPONSE\` (replaces payment-response)
 
+### Canonical Payment Lifecycle
+
+\`\`\`
+${PAYMENT_PUBLIC_LIFECYCLE}
+\`\`\`
+
+- \`submitted\` is internal relay observability only and is never caller-facing
+- \`paymentId\` is relay-owned and stays stable while a payment is in-flight
+- x402-api still uses immediate pay-per-call delivery during this phase, so in-flight payments return retryable payment errors instead of switching to a receipt-only API
+- \`checkStatusUrl\` is an additive canonical polling hint when the relay provides it
+
 ### PaymentRequiredV2 Structure (base64-decoded)
 
 \`\`\`json
 {
-  "version": 2,
-  "payTo": "SP1XXXXXXXXX",
-  "amount": "1000",
-  "asset": null,
-  "network": "stacks:1",
-  "extra": {
-    "tier": "standard",
-    "description": "0.001 STX per request"
-  }
+  "x402Version": 2,
+  "resource": {
+    "url": "/hashing/sha256",
+    "description": "x402 API - /hashing/sha256",
+    "mimeType": "application/json"
+  },
+  "accepts": [
+    {
+      "scheme": "exact",
+      "network": "stacks:1",
+      "amount": "1000",
+      "asset": "STX",
+      "payTo": "SP1XXXXXXXXX",
+      "maxTimeoutSeconds": 300,
+      "extra": {
+        "pricing": {
+          "type": "fixed",
+          "tier": "standard"
+        }
+      }
+    }
+  ]
 }
 \`\`\`
 
@@ -206,7 +237,7 @@ Legacy headers (still accepted for backward compatibility):
 GET /x402.json
 \`\`\`
 Returns machine-readable payment manifest with supported tokens, pricing tiers,
-and relay URL. Use this to auto-configure x402-stacks clients.
+relay URL, and payment lifecycle metadata. Use this to auto-configure x402-stacks clients.
 
 ## Pricing
 
@@ -1130,7 +1161,7 @@ The flow is:
 1. Client sends request WITHOUT payment → server returns 402
 2. Server response includes payment requirements (amount, recipient, token)
 3. Client creates and signs a Stacks transaction
-4. Client retries request WITH signed transaction → server verifies and processes
+4. Client retries request WITH signed transaction → server verifies, settles, and either serves the resource or returns canonical payment status
 
 ## Step 1: Initial Request (No Payment)
 
@@ -1157,24 +1188,38 @@ The \`payment-required\` header is a base64-encoded JSON object:
 
 \`\`\`json
 {
-  "version": 2,
-  "payTo": "SP1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
-  "amount": "1000",
-  "asset": null,
-  "network": "stacks:1",
-  "extra": {
-    "tier": "standard",
-    "description": "0.001 STX per request"
-  }
+  "x402Version": 2,
+  "resource": {
+    "url": "/hashing/sha256",
+    "description": "x402 API - /hashing/sha256",
+    "mimeType": "application/json"
+  },
+  "accepts": [
+    {
+      "scheme": "exact",
+      "network": "stacks:1",
+      "amount": "1000",
+      "asset": "STX",
+      "payTo": "SP1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+      "maxTimeoutSeconds": 300,
+      "extra": {
+        "pricing": {
+          "type": "fixed",
+          "tier": "standard"
+        }
+      }
+    }
+  ]
 }
 \`\`\`
 
 Fields:
-- \`payTo\`: Stacks address to pay (SP... for mainnet, ST... for testnet)
-- \`amount\`: Amount in base units (microSTX for STX, satoshis for sBTC, microUSDCx for USDCx)
-- \`asset\`: null for STX, contract principal for sBTC/USDCx
-- \`network\`: "stacks:1" (mainnet), "stacks:2147483648" (testnet)
-- \`extra.tier\`: Pricing tier (standard, dynamic, free)
+- \`resource.url\`: Resource being paid for
+- \`accepts[0].payTo\`: Stacks address to pay (SP... for mainnet, ST... for testnet)
+- \`accepts[0].amount\`: Amount in base units (microSTX for STX, satoshis for sBTC, microUSDCx for USDCx)
+- \`accepts[0].asset\`: \`STX\` for the native token, or contract principal for sBTC/USDCx
+- \`accepts[0].network\`: "stacks:1" (mainnet), "stacks:2147483648" (testnet)
+- \`accepts[0].extra.pricing\`: Pricing metadata (fixed or dynamic)
 
 ## Step 3: Build Payment Payload
 
@@ -1191,9 +1236,23 @@ For sBTC payments:
 Wrap in PaymentPayloadV2:
 \`\`\`json
 {
-  "version": 2,
-  "transaction": "0x8080000000040a...",  // hex-encoded signed Stacks tx
-  "network": "stacks:1"
+  "x402Version": 2,
+  "resource": {
+    "url": "/hashing/sha256",
+    "description": "x402 API - /hashing/sha256",
+    "mimeType": "application/json"
+  },
+  "accepted": {
+    "scheme": "exact",
+    "network": "stacks:1",
+    "amount": "1000",
+    "asset": "STX",
+    "payTo": "SP1XXXXXXXXX",
+    "maxTimeoutSeconds": 300
+  },
+  "payload": {
+    "transaction": "0x8080000000040a..."
+  }
 }
 \`\`\`
 
@@ -1232,6 +1291,20 @@ Decode \`payment-response\` to get transaction ID:
 { "version": 2, "txId": "0xabc123..." }
 \`\`\`
 
+If the relay returns canonical in-flight or terminal failure data instead of immediate success, x402-api surfaces the same public fields when available:
+
+\`\`\`json
+{
+  "error": "Payment is still in flight, please retry with the same paymentId",
+  "code": "transaction_pending",
+  "paymentId": "pay_123",
+  "status": "queued",
+  "checkStatusUrl": "https://relay.example/status/pay_123"
+}
+\`\`\`
+
+Terminal outcomes may also include \`terminalReason\`, for example \`sender_nonce_stale\`, \`queue_unavailable\`, \`broadcast_failure\`, \`nonce_replacement\`, or \`unknown_payment_identity\`. When the relay only exposes legacy details, x402-api uses compatibility-only inference after canonical parsing rather than making fallback inference the primary path.
+
 ## Token Types
 
 ### STX (default)
@@ -1298,11 +1371,17 @@ GET /x402.json
 Machine-readable payment configuration. Use this to auto-configure x402-stacks:
 \`\`\`json
 {
-  "version": 2,
-  "network": "mainnet",
-  "payTo": "SP...",
-  "tokens": ["STX", "sBTC", "USDCx"],
-  "endpoints": [...]
+  "x402Version": 2,
+  "items": [...],
+  "metadata": {
+    "paymentLifecycle": {
+      "publicStates": ["requires_payment", "queued", "broadcasting", "mempool", "confirmed", "failed", "replaced", "not_found"],
+      "submittedCallerFacing": false,
+      "inFlightIdentity": "paymentId",
+      "deliverableState": "confirmed",
+      "deliveryMode": "immediate-pay-per-call-compat"
+    }
+  }
 }
 \`\`\`
 

src/endpoints/ax-discovery.ts

@@ -7,6 +7,7 @@
 import { AIEndpoint } from "../../base";
 import type { AppContext, UsageRecord } from "../../../types";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
+import { response402, tokenTypeParam } from "../../schema";
 
 interface CloudflareAIErrorClassification {
   message: string;
@@ -132,19 +133,7 @@ export class CloudflareChat extends AIEndpoint {
         },
       },
     },
-    parameters: [
-      {
-        name: "tokenType",
-        in: "query" as const,
-        required: false,
-        schema: {
-          type: "string" as const,
-          enum: ["STX", "sBTC", "USDCx"],
-          default: "STX",
-        },
-        description: "Payment token type",
-      },
-    ],
+    parameters: [tokenTypeParam],
     responses: {
       "200": {
         description: "Chat completion response",
@@ -169,7 +158,7 @@ export class CloudflareChat extends AIEndpoint {
         },
       },
       "400": { description: "Invalid request" },
-      "402": { description: "Payment required" },
+      "402": response402,
       "404": { description: "Model not found (error_code: MODEL_NOT_FOUND, retryable: false)" },
       "429": { description: "Rate limit exceeded (error_code: RATE_LIMIT, retryable: true)" },
       "502": { description: "Upstream AI error (error_code: INTERNAL_ERROR, retryable: false)" },

src/endpoints/inference/cloudflare/chat.ts

@@ -9,7 +9,7 @@ import { BaseEndpoint } from "../../base";
 import { OpenRouterClient, OpenRouterError } from "../../../services/openrouter";
 import { logPnL } from "../../../services/pricing";
 import { lookupModel, getSimilarModels } from "../../../services/model-cache";
-import { tokenTypeParam } from "../../schema";
+import { response402, tokenTypeParam } from "../../schema";
 import type { AppContext, ChatCompletionRequest, UsageRecord } from "../../../types";
 
 export class OpenRouterChat extends BaseEndpoint {
@@ -105,7 +105,7 @@ export class OpenRouterChat extends BaseEndpoint {
         },
       },
       "400": { description: "Invalid request" },
-      "402": { description: "Payment required" },
+      "402": response402,
       "500": { description: "Server error" },
     },
   };