Proposal: Paid API Gateway architecture for x402 (OpenAPI wrappers, facilitator starter kit, operation-bound receipts, persistent SIWX proofs)

[ayushozha]

Summary

I want to propose a single architecture direction that ties together four adjacent ideas:

1. OpenAPI-to-x402 Wrapper Generator
2. Self-Hosted Facilitator Starter Kit
3. Persistent SIWX Payment History + Proofs
4. Operation-Bound Receipts

I am not proposing that all four land at once.

I am proposing that x402 consider a shared architecture for them, because they all appear to solve the same higher-level problem:

x402 already has strong payment primitives, but turning an existing API into a trustworthy paid API still requires too much bespoke glue around validation, receipts, repeat-access proofs, and facilitator deployment.

Refs: #1645, #1886, #1908, #1759, #1195, #1802

Why This Feels Like One Problem, Not Four

Today, if I want to wrap an existing API behind x402 and make it production-friendly, I need to solve all of this myself:

• how to transform an existing OpenAPI surface into x402 route declarations and middleware
• how to bind a payment to the specific validated operation being executed, not just the route
• how to support repeat access in SIWX without relying on an in-memory server-local map
• how to run a facilitator as a real service with auth, metrics, health checks, rate limits, and multi-network config

Those are currently separate pain points, but they can share one model.

Proposed Direction: PayableOperation Architecture

The core idea is to introduce a canonical intermediate model for a paid operation that tooling, receipts, SIWX, and facilitator deployment can all share.

1. PayableOperation descriptor

A PayableOperation is the canonical description of a paid endpoint or tool invocation.

Example shape:

interface PayableOperation {
  operationId: string;
  method: string;
  pathTemplate: string;
  inputSchemaRef?: string;
  pricing: PaymentOption[];
  canonicalization: "openapi-json-c14n-v1" | "none";
  receiptBinding: {
    includePathParams: boolean;
    includeQuery: boolean;
    includeBody: boolean;
    hash: "sha256";
  };
  accessPolicy?: {
    reusableViaSIWX: boolean;
    resourceKey: string;
    policyVersion: string;
  };
}

This should be creatable either:

• manually from existing x402 route configs
• or generated from an OpenAPI spec

2. operationDigest

At runtime, after request validation and canonicalization, the server computes an operationDigest from the validated request input.

For example:

sha256(
  method +
  pathTemplate +
  canonical(pathParams, query, body) +
  operationId +
  policyVersion
)

That digest becomes the thing the receipt is bound to.

This would directly address the concern raised in #1886 / #1645 that a payment receipt should prove not just "a payment happened" but "a payment happened for this exact validated operation."

3. OperationBoundReceipt

After settlement, the server/facilitator emits a structured receipt that includes:

• settlement reference (tx hash / signature / network)
• operationId
• operationDigest
• payer
• payee
• amount / asset
• optional server or facilitator signature over the receipt payload

This could either:

• extend the existing offer/receipt direction
• or become a new extension specifically for operation-bound execution proofs

This gives x402 a stronger answer for irreversible paid actions than "the route was paid at some point."

4. AccessGrantProof for SIWX

Instead of SIWX relying only on a server-local hasPaid(resource, address) store, it could persist a higher-level proof object:

interface AccessGrantProof {
  payer: string;
  resourceKey: string;
  settlementRef: string;
  operationDigest?: string;
  policyVersion: string;
  issuedAt: string;
  expiresAt?: string;
  signer: "resource-server" | "facilitator";
  signature?: string;
}

This would allow:

• persistent Redis/Postgres backends
• cryptographic "already paid" proofs instead of bare in-memory state
• future portability across restarts, deployments, and possibly services

I think this is the cleanest way to evolve SIWX without turning it into an unrelated product.

5. Facilitator Runtime Profile

The self-hosted facilitator starter kit could be defined around a standard runtime profile:

networks:
  - eip155:8453
  - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
http:
  port: 8402
  cors: ["*"]
auth:
  mode: bearer
observability:
  metrics: prometheus
  health: true
rateLimits:
  verifyPerMinute: 600
  settlePerMinute: 120
stores:
  receipts: postgres
  siwx: redis

That would let x402 ship a first-class facilitator deployment path without baking all infrastructure choices into the core SDK APIs.

How the Four Workstreams Fit

OpenAPI-to-x402 Wrapper Generator

A CLI could ingest an OpenAPI spec and generate:

• PayableOperation descriptors
• x402 route config / middleware wiring
• input canonicalization / validation hooks
• starter docs for pricing and accepts arrays
• optional proxy handlers to upstream APIs

This feels like a major adoption lever, especially for teams who already have OpenAPI and want "make this API payable" instead of "rewrite it around x402."

Self-Hosted Facilitator Starter Kit

A first-class starter kit could package:

• Docker / compose deployment
• bearer auth
• health endpoints
• metrics
• structured logs
• rate limits
• multi-network config
• persistent receipt / SIWX storage adapters

This feels adjacent to #1908 and to the general move from demos toward deployable infrastructure.

Persistent SIWX Payment History + Proofs

This becomes much cleaner if it sits on top of AccessGrantProof instead of ad hoc storage.

Short-term, this could start with:

• Redis backend
• Postgres backend
• signed proof payload format

Longer-term it could expand into portable or on-chain-verifiable proofs.

Operation-Bound Receipts

This is the most protocol-important of the four.

It creates a cryptographic link between:

• what was validated
• what was paid for
• what was settled

That seems like the right primitive if x402 wants to support more irreversible / parameterized / agentic operations safely.

Suggested Phasing

Phase 1: spec + interfaces

• define operationDigest and OperationBoundReceipt
• define a persistent SIWX storage/proof model
• decide what belongs in core vs extension vs examples

Phase 2: tooling

• ship an OpenAPI wrapper generator (likely TypeScript-first)
• generate PayableOperation descriptors and proxy scaffolds

Phase 3: deployment

• ship a self-hosted facilitator starter kit around a standard runtime profile
• include Docker, metrics, auth, health, rate limits, and persistent stores

Questions for Maintainers

1. Does this feel like the right shared architecture for these four ideas, or are they better kept separate?
2. Should operationDigest / operation-bound receipts live in core spec, an extension, or example-level guidance first?
3. Should persistent SIWX proofs be treated as a natural evolution of SIWX, or should SIWX remain intentionally server-local?
4. Would an OpenAPI wrapper generator be welcome if it started as TypeScript-only tooling outside the core protocol surface?
5. Would a facilitator starter kit be better inside this repo, or as a separate maintained template/reference deployment?

If this direction seems aligned, I'd be happy to break it into smaller follow-up proposals or implementation slices.

Would especially value feedback from @CarsonRoscoe, @murrlincoln, and @Bortlesboat on whether this belongs in core, extensions, or external tooling.

[up2itnow0822]

This proposal nails the gap. x402 has solid payment primitives, but the developer experience of wrapping an existing API still requires too much glue code around validation, receipts, and facilitator ops.

A few thoughts from our work building agent payment infrastructure:

On the architecture: The "shared architecture" approach makes sense. The four components you listed are really facets of one system - a payment policy layer that sits between the raw x402 primitives and the API developer. We see this as a module that handles:

• Budget allocation (what can this agent spend?)
• Policy enforcement (does this request comply?)
• Receipt generation (what actually happened?)

On facilitator deployment: A self-hosted starter kit would lower the barrier significantly. Most developers don't want to manage payment infrastructure - they just want their API to accept x402. The starter kit should include health checks, retry logic with idempotency keys, and a clear upgrade path as usage grows.

On receipts: Operation-bound receipts (vs. transaction-bound) are crucial for auditability. When an agent makes 50 micro-payments in a session, you need a single receipt showing the full chain - not 50 separate proofs. This matters for compliance (GDPR, SOC2) and for debugging.

Happy to dig into any of these areas more. Are you focusing on one piece first, or trying to land the whole vision?

[ayushozha]

@up2itnow0822 This is really helpful framing, thank you.

I agree that these are better thought of as one layer between raw x402 primitives and a payable API developer experience. Your "payment policy layer" description is close to how I'm thinking about it too, although I'd probably keep budget allocation adjacent rather than in the first slice, since that feels more client/wallet policy than API-wrapping policy.

I'm definitely not trying to land the whole vision at once.

My current thinking is to phase it like this:

1. Define the minimal shared interfaces first:

   • PayableOperation
   • operationDigest
   • OperationBoundReceipt
   • a persistent SIWX proof/storage model

2. Prototype the developer tooling on top of that:

   • TypeScript-first OpenAPI-to-x402 wrapper generator
   • generated route config + validation/canonicalization hooks
   • proxy/server scaffold for existing APIs

3. Treat facilitator deployment as a reference runtime/template first:

   • Docker
   • auth
   • metrics/health
   • idempotency/retry guidance
   • persistent stores
   • then pull pieces into core only if the shape proves stable

So if I had to pick one piece to start with, I'd start with the shared receipt/binding model, because that seems like the primitive that makes the other three cleaner.

Your point on operation-bound receipts vs transaction-bound receipts also resonates. I think x402 needs a way to prove "this validated operation was paid for and settled," not just "some payment tx happened."

Given your comment, this seems directionally aligned with where the project wants to go. One thing I'd love to understand from the maintainers is whether there is already active work or a preferred roadmap around any of these areas. If so, I'd rather align with that than duplicate effort. If not, I'm happy to start on the first slice independently.

Since this feels like additive new-feature work rather than a narrow bugfix, is there a preferred process to follow here? For example:

• architecture discussion in the issue first
• then a spec/extension proposal
• then a TypeScript prototype
• then upstreaming into core / other SDKs

If that's the right reading, I'm happy to start working on it. I just want to make sure I'm starting in the right place.

Concretely, do you think the best next step is:

• a spec/extension proposal in-repo for the receipt/binding model first, or
• an external TypeScript prototype that proves the shape first?

And if there is already an owner or roadmap for this area, knowing where a community contribution would be most useful would help a lot.

[Bortlesboat]

@ayushozha This sequencing makes sense.

If you’re picking a first step, it feels like the spec/extension proposal for the receipt + binding model is the right place to start.

That seems like the smallest surface to align on early, and it would make the downstream tooling (wrappers, proxies, facilitator patterns) much easier to reason about.

Happy to help think through or draft that if useful.

[ayushozha]

@Bortlesboat That makes sense.

I agree the right first slice is a spec/extension proposal for the receipt + binding model, and I'll keep it narrow so we can align on the smallest useful surface first.

Given the current spec layout, the two questions that seem most important to settle up front are:

• should this be an evolution of the existing offer-and-receipt extension, or a separate companion extension for operation binding?
• should the first draft stay limited to operationDigest + an operation-bound receipt model, and leave SIWX persistence / wrapper tooling / facilitator runtime patterns for follow-up work?

The concrete pieces I'd plan to cover in a first draft are:

• the binding target and threat model
• canonicalization inputs for the digest
• receipt payload shape and signing rules
• verifier behavior and replay / idempotency expectations
• interaction with the existing payment-identifier extension
• HTTP examples and security considerations

If that scope sounds right, I can put together a first-pass outline here or go straight to a spec PR.

[javierpmateos]

Worth noting that #1802 covers the facilitator-signed attestation side of this (settlement proof with txHash, amount, fee). The OperationBoundReceipt proposed here and the facilitator-attestation in #1802 could compose well — one binds to the operation, the other binds to the settlement. Happy to coordinate.

[up2itnow0822]

@ayushozha @Bortlesboat -- glad the "payment policy layer" framing resonated. And agreed on keeping budget allocation out of the first slice - that's wallet/client territory, not API-wrapping infrastructure.

On the sequencing question: starting with the receipt + binding spec extension makes sense. A few concrete things that would help us integrate downstream:

operationDigest canonicalization needs to be strict and deterministic. JSON field ordering, whitespace normalization, and encoding of optional fields all need to be specified exactly. We've been bitten by this in practice - two implementations computing slightly different digests for the same logical operation because one sorted keys and the other didn't. The openapi-json-c14n-v1 you proposed is the right call, but the spec should define exactly which JSON Canonicalization Scheme it follows (RFC 8785 would be my recommendation).

On whether this extends offer-and-receipt or becomes a companion extension: I'd lean toward companion. The existing offer/receipt flow handles the payment lifecycle. Operation binding handles the "what did you pay for" lifecycle. They compose but they're different concerns. Coupling them means every receipt format change cascades into the operation binding spec.

One practical addition for the facilitator starter kit: a health check endpoint that reports not just "am I running" but "am I correctly configured for networks X, Y, Z and can I reach settlement endpoints." We found in production that half the facilitator issues are config problems that only show up at settlement time, not at verify time.

Happy to review or contribute to the spec draft when it's up.

[ayushozha]

Started the first slice as a draft PR here: #1932

It stays intentionally narrow and only proposes a separate operation-binding companion extension in specs/extensions/operation-binding.md.

The draft covers:

• goals / non-goals
• threat model
• exact operationDigest inputs
• exact canonicalization rules (RFC 8785 + SHA-256)
• operation receipt shape
• verifier behavior
• interaction with payment-identifier
• composition with offer-and-receipt and Facilitator-side attestation to complement offer-receipt — coordination proposal #1802
• HTTP examples

If this looks like the right first-step shape to maintainers, happy to iterate there and then follow with implementation or adjacent proposals from the same thread.

[ThomsenDrake]

This is a compelling proposal — the "PayableOperation" abstraction that sits between raw x402 primitives and payable API DX is exactly the layer that's missing today.

One data point from the Bitcoin/Lightning side: we've been building btcpay-mcp, an MCP server that exposes BTCPay Server's full merchant API (invoice creation, Lightning payments, store management, webhook handling) to AI agents. BTCPay Server already supports multi-currency invoicing, automatic Lightning/network settlement, and self-hosted deployment — which maps closely to the "Self-Hosted Facilitator Starter Kit" idea in point 2.

The current x402 SDKs ship EVM and SVM scheme support. Bitcoin/Lightning would be a natural network addition, and BTCPay's architecture (self-hosted, no intermediary, per-invoice payment tracking) aligns well with the operation-binding receipt model proposed here — each BTCPay invoice already has a unique ID, payment proof, and settlement status that could serve as the operation-bound receipt.

Happy to contribute if there's interest in a Bitcoin/Lightning facilitator reference implementation. The facilitator pattern in x402's spec is network-agnostic by design, so BTCPay could plug in as a settlement backend without changes to the core protocol.

cc @ayushozha — would a Bitcoin scheme facilitator sketch be useful as a companion to #1932?

[aeoess]

The "four ideas that are really one problem" diagnosis is correct. We've been running a production enforcement gateway that solves the same architectural problem — the layer between raw payment primitives and trustworthy paid API operations.

Our implementation at gateway.aeoess.com handles the pieces you described:

Operation binding: every API call through the gateway produces a 3-signature receipt chain — the agent signs intent before execution, the policy engine signs the evaluation, the gateway signs the execution result. The receipt binds the exact parameters, the delegation scope that authorized them, and the payment amount. This is your "operation-bound receipt" with cryptographic non-repudiation.

Payment policy layer: the gateway evaluates 15 constraint dimensions in under 2ms before any operation executes. Scope authorization, spend limits (cumulative, not per-call), temporal validity, revocation status, reputation threshold. This is the "payment policy" that sits between the facilitator and the API — deterministic, auditable, and replay-verifiable.

Repeat-access proofs: the Merkle-committed receipt ledger serves as proof of prior access. An agent that accessed an API 50 times has 50 signed receipts in a hash chain. A verifier can check any individual receipt without seeing the full chain (selective disclosure via Merkle inclusion proofs).

Facilitator deployment: the gateway runs as a single deployable service (Railway, Docker, or standalone). One binary handles policy evaluation, receipt signing, and audit logging. No bespoke glue between components.

The architecture converges: your PayableOperation abstraction maps to our ActionIntent → PolicyDecision → ActionReceipt pipeline. The difference is that ours is already deployed and processing evaluations.

For the OpenAPI wrapper generator (#1932): an APS adapter that reads an OpenAPI spec and generates delegation scopes per endpoint would be a clean integration. GET /data → scope: data_read, POST /trade → scope: commerce + spendLimit. The scope mapping from API surface to governance constraints is mechanical.

Happy to share the gateway architecture or contribute to the shared design. The enforcement pattern is framework-agnostic — it works above x402, not instead of it.

[ThomsenDrake]

This is exactly the kind of real-world implementation signal the spec needs. A few thoughts on convergence:

The settlement gap: Your ActionIntent → PolicyDecision → ActionReceipt pipeline handles the policy and attestation layers cleanly. But the actual payment settlement — receiving funds, confirming on-chain/Lightning finality, handling refund flows — still needs to happen somewhere. That's where a settlement adapter like btcpay-mcp fits: your gateway decides whether and how much, the settlement adapter executes the transfer.

Scope mapping from OpenAPI is mechanical but valuable. For #1932: an APS adapter that generates delegation scopes from OpenAPI specs (as you described: GET /data → scope: data_read) would be a clean first integration point. The spec could standardize the scope naming convention and let facilitators implement their own evaluation logic.

On the receipt chain: The 3-signature model (agent intent + policy evaluation + gateway execution) is stronger than single-signature receipts because it's non-repudiable across three independent parties. This should be a recommended pattern in the spec, not just an implementation detail.

The gateway architecture doc would be valuable context for the #1932 operation-binding extension. Would you be open to sharing it (even as a design doc/gist) so ayushozha can reference it when designing the OpenAPI adapter?

[aeoess]

@ThomsenDrake — the BTCPay settlement adapter maps cleanly onto the architecture. You're right about the gap: our gateway handles the authorization pipeline (should this agent be allowed to spend this much on this operation?) but the actual fund movement — on-chain confirmation, Lightning finality, refund flows — needs a settlement layer. BTCPay's per-invoice tracking with payment proof and settlement status is the right abstraction for that layer.

The architecture split:

Agent → Gateway (policy evaluation) → Settlement Adapter (BTCPay/x402/Stripe) → Chain
         ↓                                    ↓
    PolicyDecision receipt              SettlementReceipt
         ↓                                    ↓
    ActionReceipt (3-sig: agent + gateway + settlement)

The 3-signature receipt works because each signer attests to something different: the agent signed intent ("I want to do X"), the gateway signed authorization ("X is within scope and budget"), and the settlement adapter signed execution ("X was settled on-chain at txid Y"). Non-repudiation across three independent trust domains.

On sharing the gateway architecture: happy to publish a design doc. The core is straightforward — 15 constraint dimensions evaluated in under 2ms, append-only receipt ledger with hash chain, delegation chain verification with cascade revocation. I'll put together a gist that @ayushozha can reference for #1932.

On the scope naming convention from OpenAPI: the mechanical mapping works for CRUD operations (GET → read, POST → write, DELETE → admin). Where it gets interesting is composite operations — an endpoint that reads data AND triggers a payment. The scope should be the union ([data_read, commerce]), and the gateway evaluates each scope facet independently. This is the product lattice model from our Faceted Authority Attenuation paper — each scope dimension narrows independently, and the effective scope is the meet of all dimensions.

A Bitcoin/Lightning facilitator reference implementation would be a strong addition to the spec. The network-agnostic design is the whole point — if the 3-sig receipt model works across EVM, SVM, and Lightning, it's a real protocol, not an Ethereum-specific tool.

[ThomsenDrake]

@aeoess — this is converging well. A few notes:

On the design doc for #1932: The 3-sig receipt model maps directly to what btcpay-mcp already implements — each BTCPay invoice carries a payment_proof (transaction hash or Lightning preimage) that the settlement adapter can sign as attestation. The adapter would emit SettlementReceipt { invoice_id, method, txid/preimage, amount, confirmed_at } — your gateway's ActionReceipt composition would be the meet of these three independent attestations.

On faceted scope evaluation: The union-scope model for composite endpoints is elegant. For Lightning-specific operations (invoice creation, payment, refund), the scope facets would be roughly:

• payment_initiate — create invoice/request payment
• payment_settle — confirm on-chain or Lightning finality
• payment_refund — partial or full refund handling
• data_read — query invoice/payment status

A payment endpoint that creates an invoice AND records it would evaluate [payment_initiate, data_read] independently, with each facet subject to its own budget constraint. This maps cleanly to BTCPay's role-based invoice permissions.

On scope naming from OpenAPI → x402: For the Bitcoin/Lightning case, I'd suggest a settlement: prefix convention: settlement:initiate, settlement:confirm, settlement:refund, settlement:read. This keeps the scope vocabulary composable with the existing x402 scope lattice while making the settlement layer's role explicit.

Happy to prototype the settlement adapter against your design doc once it's published. The btcpay-mcp codebase already handles invoice lifecycle, payment proof extraction, and multi-method settlement — the adapter would be a thin mapping layer.

[aeoess]

@ThomsenDrake — the settlement: prefix convention is clean and I'd adopt it. It keeps the scope vocabulary composable while making the settlement layer's boundaries explicit. The full scope lattice for a payment endpoint would then be:

[settlement:initiate, data_read]  →  each facet evaluates independently
                                     settlement:initiate checks spend budget
                                     data_read checks data access scope

On the SettlementReceipt shape: { invoice_id, method, txid/preimage, amount, confirmed_at } is the right minimal set. The gateway's ActionReceipt would compose as:

ActionReceipt = {
  intent:     AgentSignature(request),
  policy:     GatewaySignature(evaluation),
  settlement: AdapterSignature(SettlementReceipt)
}

Each signature attests to its layer. A verifier can check any layer independently — you can verify the settlement happened (Lightning preimage) without trusting the gateway's policy evaluation, and vice versa.

I'll put the design doc together as a gist this week. The core sections: constraint dimensions, evaluation pipeline, receipt format, delegation chain verification, and the settlement adapter interface. Will tag you and @ayushozha when it's up.

On the Bitcoin facilitator: the network-agnostic 3-sig model working across EVM + SVM + Lightning is the proof that it's a real protocol. If you want to start sketching the btcpay-mcp adapter against the receipt interface, the relevant types are in agent-passport-system under src/commerce.ts — CommercePreflight, ActionReceipt, and SettlementVerification.

[ThomsenDrake]

@aeoess — the scope lattice model is clean. One practical note for the spec:

Cross-rail settlement receipt normalization: Different payment rails return different proof shapes. On-chain BTC gives you a txid, Lightning gives you a payment_preimage, and Stripe gives you a charge_id. The SettlementReceipt needs a proof_type discriminator so the gateway's ActionReceipt composition can verify each rail's attestation independently without hardcoding rail-specific logic.

SettlementReceipt = {
  invoice_id: string,
  method: "bitcoin_onchain" | "bitcoin_lightning" | "usdc_base" | "stripe",
  proof_type: "txid" | "payment_preimage" | "charge_id",
  proof: string,  // the actual proof value
  amount: number,
  confirmed_at: ISO8601
}

This keeps the settlement: scope checks rail-agnostic — the gateway evaluates settlement:initiate against the budget regardless of which adapter handles the actual transfer. The adapter's job is just to normalize into this common shape.

Worth including in #1932's adapter interface spec?