Add structured decline/failure context for payments

[0xtotaylor]

Abstract

Extend x402 with optional intent traces so clients can explain why they decline to pay and servers can return structured context when verification/settlement fails. Adds an intent_trace object (reason_code, trace_summary, metadata, optional remediation) to decline messages and failure responses, with transport bindings for HTTP headers, A2A metadata, and MCP _meta.

Motivation

Today a declined or failed x402 payment is a dead end: clients stay silent or servers return terse codes (e.g., insufficient_funds) with no signal about budget, network, or timing constraints. This forces guesswork in pricing and UX. Structured intent traces turn non-payments into actionable signals: a decline with price_sensitivity or timing_deferred tells the server whether to counter-offer now or follow up later; a failure trace with signature_expired plus remediation hints lets clients retry successfully.

Why structured and bidirectional?

• Structured codes power routing and analytics; free text does not. Codes cover client-side decisions (price, network/asset, trust, timing) and server-side failures (insufficient_funds, signature_invalid/expired, transaction_reverted, etc.), with an extensible enum.
• Bidirectional: Clients send decline traces; servers send failure traces (verify/settle) with optional remediation so agents can auto-resolve.
• Optional: Preserves backward compatibility. Non-supporting parties ignore traces and continue the protocol.

Specification

• New message: PaymentDecline may include intent_trace.
• Extended responses: VerifyResponse and SettleResponse may include intent_trace and optional remediation.
• Reason codes:
  • Client declines: price_sensitivity, budget_exceeded, wrong_network, wrong_asset, insufficient_balance, untrusted_facilitator, untrusted_recipient, timing_deferred, comparison, rate_limit_concern, gas_cost_concern, authorization_denied, other.
  • Server failures: insufficient_funds, signature_invalid, signature_expired, signature_not_yet_valid, amount_mismatch, recipient_mismatch, nonce_already_used, network_mismatch, asset_mismatch, transaction_reverted, transaction_timeout, facilitator_error, smart_wallet_error, other.
• Schema rules:
  • metadata: flat object; values are string/number/boolean only; no arrays/nested objects.
  • Monetary values: strings in atomic units (x402 convention).
  • remediation: optional action hint (e.g., top_up, retry_with_fresh_authorization, switch_network).
  • Lenient enum: Enums are for documentation/tooling; validators SHOULD accept unknown reason_code values and treat them as other (forward compatibility).
• Transports:
  • HTTP: PAYMENT-DECLINE header (base64url PaymentDecline JSON); server may return X-PAYMENT-INTENT-TRACE with failure context.
  • A2A: metadata keys x402.payment.status, x402.payment.intent_trace.
  • MCP: _meta block under x402/payment with decline and intent_trace.
• Semantics:
  • Traces are optional and write-only; protocol must proceed even if traces are ignored.
  • Unknown reason codes MUST NOT cause errors.
  • Structurally invalid traces should be ignored/logged, not block the flow.

Privacy

• Intent traces are explicit, scoped to the resource server, and encourage structured data to avoid leakage.
• Clients SHOULD avoid PII in trace_summary; secrets (keys, auth) must never be included.

Files Changed

• x402/specs/rfc-intent-traces.md — Spec, examples, transports, conformance, and validator guidance.
• Go: go/http/client.go, go/http/client_test.go, go/http/server.go, go/types.go — Header encode/decode, decline handling, types.
• Java: java/src/main/java/.../IntentTrace.java, PaymentDecline.java, Remediation.java, SettlementResponse.java, VerificationResponse.java, SettlementResponseHeader.java, PaymentFilter.java — Types plus HTTP filter wiring.
• Python: python/x402/src/x402/encoding.py, middleware.py, types.py, tests/test_encoding.py — Header helpers, middleware, types, tests.
• TypeScript: typescript/packages/core/src/index.ts, typescript/packages/core/src/http/x402HTTPResourceServer.ts, typescript/packages/mechanisms/evm/src/exact/facilitator.ts — Exports, HTTP resource server handling, facilitator intent trace helpers.

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[vercel]

@0xtotaylor is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.