feat: support per-route resource metadata and x402 extensions in createGatewayMiddleware

[riyannode]

Feature request

I'm using @circle-fin/x402-batching@3.5.0 with
createGatewayMiddleware().

The current middleware constructs the x402 PaymentRequired.resource
internally, while the route protection API is exposed as:

gateway.require("$0.01")

From the current public API surface, there does not appear to be a
supported route-level way to provide:

• resource.url
• resource.description
• resource.mimeType
• PaymentRequired.extensions
• extensions.bazaar

while continuing to use the existing Gateway middleware.

Current limitation

GatewayMiddlewareConfig provides a global description, but route
metadata is otherwise constructed internally.

For applications exposing multiple paid endpoints, this prevents each
route from supplying its own resource metadata and x402 extensions
without moving to a lower-level payment-server integration.

Requested API

Would Circle consider exposing route-level metadata, for example:

gateway.require("$0.01", {
  resource: {
    url: "https://api.example.com/v1/resource",
    description: "Endpoint-specific description",
    mimeType: "application/json"
  },
  extensions: {
    bazaar: {
      // extension declaration
    }
  }
})

or an equivalent supported API?

The exact shape is only illustrative; the main request is a supported
way to provide resource metadata and x402 extensions per protected route.

Motivation

This would allow applications to emit richer x402 v2 discovery metadata
while preserving the existing Circle Gateway middleware path for:

• payment requirement generation
• verification
• settlement
• lifecycle hooks
• Gateway batching behavior

Today, adding this metadata appears to require replacing
createGatewayMiddleware() with a lower-level x402 resource-server
integration even when the existing payment behavior does not otherwise
need to change.

Environment

• @circle-fin/x402-batching: 3.5.0
• @x402/core: 2.21.0
• @x402/evm: 2.21.0
• Runtime: Bun 1.3.14
• Framework: Express 5.2.1

Additional context

I can provide a minimal reproduction or test a proposed API if useful.

[osr21]

Adding a machine-economy use case where this gap is directly visible.

We run a policy-guarded device wallet on Arc Mainnet — a MachineWallet contract (0x27b3F5776494f7a3f63e71B2F601e463aA97FBb0, source) that enforces per-payment caps, a rolling window spend limit, and a max acceptable unit price before executing a USDC transfer. The wallet operates autonomously: on each tick it evaluates the current spot price of electricity (kWh) and calls pay() if the price is within policy.

From an x402 integration perspective, the routes that feed this wallet represent genuinely different resources:

Route	Resource	Metadata a client needs
/market/price	Current spot kWh price	mimeType: "application/json", price range, unit
/energy/buy	0.1 kWh electricity credit	description with kWh amount + device ID, acceptable price ceiling
/capacity/reserve	Future delivery slot	extensions with auction price + slot ID

With a global description only, all three routes look identical to an x402 client. A machine agent validating "am I paying for what I think I'm paying for?" has no way to verify the resource identity at the route level before signing.

The extensions field is particularly relevant here: in a machine economy context it could carry the device's on-chain policy parameters (max unit price, window cap) so a buyer can verify the quoted price matches the contract policy before submitting — effectively letting the contract enforce the terms that the x402 discovery layer advertises. That closes the loop between the HTTP payment negotiation and the on-chain enforcement.

Per-route resource metadata + extensions would let createGatewayMiddleware cover this pattern without requiring a custom resource-server just to attach device context to each route.