[Feature Request] Add new `exact-split` scheme for native facilitator fee support

[fretchen]

Summary

Propose adding a new exact-split scheme to x402 that enables facilitators to charge fees while allowing sellers to use standard x402 payment requirements without any code changes.

Motivation

Currently, x402 facilitators face a challenge when implementing fee-based business models:

Current Situation	Problem
Facilitator wants to charge a fee	Seller must adapt their code
Seller specifies payTo: sellerAddress	Fee must be handled outside x402
Standard "exact" scheme	No built-in fee mechanism

Real-world use case: A public facilitator (no whitelist) wants to charge 0.01 USDC per transaction. Today, this requires:

1. Seller changes payTo to a splitter contract address
2. Seller adds extra.seller field with their own address
3. Seller calculates amount + fee themselves
4. Both parties must coordinate on the fee structure

This breaks the simplicity of x402 and creates integration friction.

Buyer-Side Complexity

Without native x402 support for fee-based schemes, buyers face significant friction:

• Must implement a custom SchemeNetworkClient (EIP-712 signing, nonce calculation, payload transformation)
• Lose the "just use @x402/fetch" simplicity that makes x402 attractive
• Each fee-based facilitator requires custom client-side code

This creates an adoption blocker for community/small facilitators:

1. Large, well-funded entities can offer "free" facilitation (subsidized by other business models)
2. Community facilitators need transaction fees to sustain operations
3. But buyers won't adopt complex custom schemes → facilitators can't charge fees → only centralized players remain

So from my view native fee support is crucial for a diverse, decentralized facilitator ecosystem. I do not see how I would run one without fees.

Proposed Solution: exact-split Scheme

A new scheme that transforms standard payment requirements internally:

┌─────────────────────────────────────────────────────────────┐
│  Seller's PaymentRequirements (STANDARD!)                   │
│  ─────────────────────────────────────────                  │
│  scheme: "exact-split"                                      │
│  payTo: "0xSeller..."        ← Seller's own address         │
│  amount: "20000"             ← What seller wants (0.02 USDC)│
└─────────────────────────────────────────────────────────────┘
                              ▼
                    ExactSplitEvmScheme
                      transforms to:
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  EIP-712 Authorization (signed by buyer)                    │
│  ───────────────────────────────────────                    │
│  to: "0xSplitter..."         ← Splitter contract            │
│  value: "30000"              ← amount + fee (0.03 USDC)     │
│  nonce: keccak256(seller, salt)                             │
└─────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  PaymentPayload.payload                                     │
│  ─────────────────────                                      │
│  authorization: { from, to, value, ... }                    │
│  seller: "0xSeller..."       ← For settlement               │
│  salt: "0x..."               ← Random, for nonce uniqueness │
│  originalAmount: "20000"     ← What seller receives         │
│  fee: "10000"                ← Facilitator fee              │
└─────────────────────────────────────────────────────────────┘

Technical Design

1. SchemeNetworkClient Implementation

class ExactSplitEvmScheme implements SchemeNetworkClient {
    readonly scheme = "exact-split";
    
    async createPaymentPayload(
        x402Version: number,
        requirements: PaymentRequirements
    ): Promise<Pick<PaymentPayload, "x402Version" | "payload">> {
        // 1. Get seller from requirements.payTo
        // 2. Generate random salt
        // 3. Compute nonce = keccak256(abi.encode(seller, salt))
        // 4. Transform: to = splitterAddress, value = amount + fee
        // 5. Sign EIP-712 TransferWithAuthorization
        // 6. Return payload with seller, salt, originalAmount, fee
    }
}

2. Nonce Calculation

// On-chain in Splitter contract:
bytes32 nonce = keccak256(abi.encode(seller, salt));

This ensures:

• Each seller+salt combination produces a unique nonce
• Replay protection is maintained
• Seller address is cryptographically bound to the authorization

3. Splitter Contract Interface

interface IEIP3009Splitter {
    function splitTransferWithAuthorization(
        address from,
        address seller,
        uint256 totalAmount,
        uint256 validAfter,
        uint256 validBefore,
        bytes32 salt,
        bytes calldata signature
    ) external;
}

The contract:

• Receives totalAmount from buyer
• Sends totalAmount - fixedFee to seller
• Sends fixedFee to facilitator wallet
• All in one atomic transaction

Facilitator /supported Response

{
  "x402Version": 2,
  "kinds": [
    {
      "scheme": "exact-split",
      "network": "eip155:10",
      "asset": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
      "extra": {
        "splitterAddress": "0x...",
        "fixedFee": "10000",
        "feeDescription": "0.01 USDC fixed fee per transaction"
      }
    }
  ]
}

Benefits

Aspect	Standard "exact"	Proposed "exact-split"
Seller code changes	Must adapt for fees	None required
Fee transparency	Off-chain agreement	On-chain, verifiable
Atomic settlement	N/A	Single transaction
Buyer trust	Must trust facilitator	Contract-enforced split

Open Questions

1. Scheme naming: Should it be exact-split, exact-fee, or something else?

2. Fee discovery: How should the fixedFee be communicated?

   • Option A: In /supported response extra field
   • Option B: Standardized field in PaymentRequirements
   • Option C: Query endpoint on splitter contract

3. Variable fees: Should the scheme support percentage-based fees, or only fixed fees?

4. Multi-recipient splits: Should we generalize to N recipients (e.g., royalties)?

5. Nonce pattern: Is keccak256(seller, salt) the right approach, or should we use a different binding?

On question 3 and 4 I would prefer a "simple" solution for the start.

Reference Implementation

A working PoC is available demonstrating:

• Custom ExactSplitEvmScheme class implementing SchemeNetworkClient
• Full verify/settle flow with balance verification

EIP3009SplitterV1 Contract on Optimism Sepolia:

• Address: 0x7e67bf96ADbf4a813DD7b0A3Ca3060a937018946
• Etherscan: https://sepolia-optimism.etherscan.io/address/0x7e67bf96ADbf4a813DD7b0A3Ca3060a937018946

Next Steps

I'm happy to contribute a full implementation (client-side scheme + facilitator logic) as a PR. However, I'd appreciate feedback on the general approach and the open questions above before investing time in a polished PR.

Specifically looking for input on:

• Is this the right direction for fee support in x402?
• Any concerns with the nonce binding pattern?
• Preferences on scheme naming and fee discovery mechanism?

[phdargen]

Thanks a lot for the proposal @fretchen! A protocol native way for facilitators to charge fees would be a very valuable addition.

An initial thought, without having checked your proposal in detail yet, is if we could find a more modular approach here. For now there is only exact, but more schemes are coming. Then we would need exact-split, 'up-to-split' etc. I feel rather than defining a new scheme, implementing a fee-splitter extension may be the way to go.

Please have a look at https://github.com/coinbase/x402/tree/main/typescript/packages/extensions if that would make senes for your proposal

[notorious-d-e-v]

Great proposal and agree that it might work better as an extension.

All for supporting this as we've been looking at something similar.

[fretchen]

Thanks for the feedback guys. I analyzed with the help of Claude Opus whether the existing @x402/extensions package could help (as suggested). However, it seems that extensions are currently observational only (Bazaar discovery), not transformational. They further seem to work on Server/Facilitator side, not on x402Client (Buyer).

Where Can Transformation Happen?

Looking at the buyer's three lines:

const client = new x402Client();
registerExactEvmScheme(client, { signer });
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

Layer	Can Transform?
wrapFetchWithPayment	❌ No (only delegates)
x402Client	✅ Yes (before/after delegating to scheme)
SchemeNetworkClient	✅ Yes (but requires new scheme)

This leads to two approaches:

Approach A: New Scheme (my original proposal)

• Scheme name changes: exact → exact-split
• Buyer registers new SchemeNetworkClient
• Works today, no core changes needed
• But: plenty of implementations

Approach B: Client Transformers (more modular)

• Scheme name stays: exact
• Client applies transformers before delegating to scheme
• One implementation per feature
• Requires core change to x402Client

// Facilitator's /supported response
{
  "scheme": "exact",
  "extra": { "transformer": "fee-split", "splitter": "0x...", "fee": "10000" }
}

// Buyer code (minimal change)
const client = new x402Client();
registerExactEvmScheme(client, { signer });
client.registerTransformer("fee-split", feeSplitTransformer);  // ← NEW

// Inside x402Client.createPaymentPayload():
// 1. Apply transformer (modify requirements)
// 2. Delegate to scheme (signs transformed data)

My feeling on fees as a core concept

Approach B is more elegant, but likely plenty of work ? But I'd go further:

Fees are fundamental to any payment system (credit cards, PayPal, Stripe). Currently they feel to me within x402 as an extension. Long-term, the ideal would be:

// Future: Fees are automatic, not opt-in
const client = x402Client.fromFacilitator("https://facilitator.example.com", { signer });
// Client automatically discovers: schemes, networks, fees
// Buyer writes zero fee-related code

This would require fees to be a first-class concept in the x402 spec, not an optional transformer.

Summary

1. Limits of existing extensions: I do not really see how to implement fee-splitting as an extension today, given the current architecture.
2. How to proceed? I somehow like the idea of the modular transformer approach, but it requires core changes. So this is a bigger discussion. It directly connect to the question of fees become a core concept? I would argue yes but this can easily become a rabbit hole.
3. Extension of extensions? If the extensions package is extended to support client-side transformers, that could be a path to Approach B.

Happy to help with either direction. What are your thoughts ?

[notorious-d-e-v]

My thoughts below --

Goals

Imo the goal is for the buyer to have as abstracted of a view as possible when it comes to blockchains.

They shouldn't even need to know what gas fees are.

Ideally the same goes for the merchant.

And the role of the facilitator is to make that as invisible as possible for the merchant.

By leveraging a facilitator, the merchant is getting value-add service(s) and should pay a fee for those.

Those fees are a merchant <> facilitator concern imo, and don’t need to involve the client.

If the merchant later wanted to raise the price of their offerings to offset the fees that they're paying to run their business that's on them.

Merchant <> Facilitator

Building on the idea of this being a merchant <> facilitator concern.

It would be ideal if the merchant paid the facilitator via x402.

After all, x402 is a standard that we're building for payments.

Simple Version

A simple form of it would be this:

1. Merchant is the buyer (client).
2. Facilitator is the merchant (server).

The merchant does a separate x402 tx to pay the facilitator, before getting access to certain services.

The facilitator (acting as a merchant), stores the merchant's payment and data in its own records and serves up the merchant on subsequent requests.

This is how we're building the current version of facilitator fees at PayAI.

The merchant (acting as a buyer) tops up credits via x402, and can authorize various merchant wallets to spend those credits.

More Elegant?

Another way that is perhaps more elegant and transactional would be to have it as an extension as part of the same x402 flow.

For example:

Merchant calls GET /supported on the facilitator

Facilitator responds with

{
  "kinds": [...],
  "extensions": [
    "facilitator-fees": {
      "info": {
        "fees": {
          "service": "amount",
          ...
      },
      "schema": {...}
    }
  ],
  "signers": [...]
}

The merchant would then continue with its regular flow between merchant <> client.

Then when the merchant forwards the PaymentPayload to the facilitator during requests to /verify and /settle, it can also include a PAYMENT-SIGNATURE header in which the merchant is making a payment to the facilitator.

The facilitator would accept the merchant's payment first, and then process the client’s PaymentPayload after.

This could simplify the process so that merchant and facilitator get paid in the same x402 tx cycle.

However, it also adds complexity.

Another alternative would be to re-architect the spec to allow for fees for facilitators.

Conclusion

In my opinion, and after typing this out, it seems like having two separate x402 transactions is much simpler and cleaner.

Why complicate the x402 primitive when the primitive itself can be used to pay the facilitator for its service offering?

In the merchant <> facilitator relationship, the merchant is the buyer/client, and the facilitator is the merchant/server.

Technically x402 is a spec between client and server and the facilitator is optional.
Should we overload it to handle payments to the facilitator?

[fretchen]

Just for reference. I wonder if this is connect to #1016

[Kbhat1]

Just for reference. I wonder if this is connect to #1016

Both proposals are complementary, #937 addresses how fees are collected while #1016 is how fees are disclosed. A facilitator could use #1016 to advertise their fee structure and #937's splitter to enforce it trustlessly.

I do think #1016 sits at a layer lower, given fee-aware multi-facilitator routing requires standardized disclosure regardless of the collection mechanism (whether that's an on-chain splitter, a separate x402 transaction, etc).

[fretchen]

@Kbhat1 thanks for the explanation.

@notorious-d-e-v thanks for the refinement, I will comment below. I understand the goals as follows:

• Goal 1: Abstraction for Buyer and Merchant
• Goal 2: Fees are Merchant ↔ Facilitator Concern
• Goal 3: Keep x402 Primitive Simple

I agree with them and think that the splitter approach can meet them too.

Analysis: Does A Splitter Approach Meet These Goals?

Clarification on "Invisible Fees"

First, let's clarify: The merchant must know the fee structure, just like he does for Stripe etc. What should be invisible is the technical complexity, not the business terms. Agreed?

Aspect	Should be invisible?
Fee percentage	❌ No - Merchant must know their costs
Gas fees	✅ Yes - Facilitator abstracts this
Splitter contract address	✅ Yes - Technical detail
EIP-3009 mechanics	✅ Yes - Implementation detail

Evaluation of Approach B (Client Transformer + Splitter)

Goal	Met?	Analysis
Buyer abstraction	✅	Buyer code unchanged, transformer is automatic
Merchant abstraction	⚠️	Merchant's 402 must return splitter as recipient, not their own address
Fees don't involve client	✅	Client signs to splitter, unaware of fee split
Keep x402 simple	⚠️	Requires transformer concept in client

Problem: The previous Approach B requires the merchant to know about the splitter address and include it in their 402 response. This violates Goal 2.

Approach B Refined: Meeting Goal 2

To meet Goal 2 while staying trustless, I propose to move the recipient transformation from the merchant's code to the x402Client.

This means:

• Merchant code stays 100% unchanged - they just return their own address
• x402Client reads /supported - sees extra.splitter in facilitator's response
• x402Client auto-transforms - replaces recipient: merchant with recipient: splitter before signing

// Merchant's code (UNCHANGED - knows nothing about splitter)
return new Response(null, {
  status: 402,
  headers: { "X-Payment": JSON.stringify({
    recipient: myAddress,  // ← Just their own address
    amount: "1000000"
  })}
});

// Facilitator's /supported response (includes splitter info)
{
  "kinds": [{ 
    "scheme": "exact", 
    "extra": { "splitter": "0xSplitter...", "feeBps": 500 }
  }]
}

// x402Client (automatic transformation before signing)
// 1. Sees: recipient = 0xMerchant (from 402)
// 2. Sees: splitter = 0xSplitter (from /supported)
// 3. Transforms to: recipient = 0xSplitter
// 4. Signs EIP-3009 to Splitter (merchant address stored in payload)

How This Meets All Goals

Goal	Met?	How
Buyer abstraction	✅	x402Client does transformation automatically
Merchant abstraction	✅	Merchant just returns their own address
Fees don't involve client	✅	Client signs to splitter, doesn't know about fees
Keep x402 simple	✅	Core spec unchanged, transformation is client-side
Trustless	✅	Fee split is on-chain, immutable, atomic

Comparison: Separate x402 vs. Atomic Splitter

I think that it is also helpful to see when the payAI approach and the atomic splitter are helpful:

Aspect	Separate x402 (notorious-d.e.v.)	Atomic Splitter (this proposal)
Trustless	❌ Requires credit/account relationship	✅ On-chain, atomic
Merchant code	✅ Unchanged	✅ Unchanged
Buyer code	✅ Unchanged	✅ Unchanged (with transformer)
Fees invisible to buyer	✅ Yes	✅ Yes
Atomic execution	❌ Two separate transactions	✅ Single transaction
Spec changes needed	❌ None	⚠️ Client transformer concept
Pre-funding required	⚠️ Merchant pre-pays credits	❌ No

Conclusion

Both approaches have merit:

1. notorious-d.e.v.'s separate x402: Simpler, no spec changes, works today. But requires trust/credit relationship between merchant and facilitator.

2. Atomic Splitter with Client Transformer: Trustless, atomic, meets all abstraction goals. But requires the transformer concept in x402Client.

My feeling: The x402 spec should support both models:

• Default exact scheme: Facilitator fees are out-of-band (merchant's concern)
• Optional transformer/splitter: For trustless, atomic fee collection

This gives facilitators flexibility to choose their business model while keeping the core spec simple. @notorious-d-e-v did I get your points right ?

If others agree on the transformer approach, I can try to help draft the necessary changes to x402Client and the spec.