Proposal: standardize facilitator attribution for x402 settlements

[danielnorkin]

Proposal

Add a standard facilitator-attribution extension to make x402 settlement facilitator identity observable without relying on heuristic address labeling.

Suggested spec location:

specs/extensions/facilitator-attribution.md

Motivation

x402 can verify and settle payments, but third-party observers cannot reliably determine which facilitator handled a settlement from chain data alone.

This matters for:

• settlement analytics
• user support after facilitator timeouts
• marketplace trust signals
• facilitator compliance monitoring
• neutral x402 activity tapes
• demand intelligence and ecosystem reporting

Today, generic payment primitives such as EIP-3009, Permit2, Solana SPL transfers, or sponsored transactions do not by themselves encode facilitator identity. /supported.signers helps, but it is not expressive enough to capture signer role, validity windows, or the actual facilitator used for a given settlement.

For products like Tape and Demand Intel, this creates a hard distinction between “we observed an x402-adjacent payment primitive” and “we can prove which x402 facilitator handled this settlement.” Standardizing this would help the broader ecosystem, not just one implementation.

Proposed extension identifier

"facilitator-attribution"

Proposed /supported shape

Facilitators that support this extension SHOULD include structured signer metadata in /supported.

{
  "schemes": ["exact"],
  "networks": ["eip155:8453", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"],
  "extensions": ["bazaar", "facilitator-attribution"],
  "signers": {
    "eip155:8453": [
      {
        "address": "0xabc...",
        "role": "settler",
        "schemes": ["exact"],
        "validFrom": 1760000000,
        "validUntil": null
      }
    ],
    "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": [
      {
        "address": "FEE_PAYER_PUBKEY",
        "role": "fee_payer",
        "schemes": ["exact"],
        "validFrom": 1760000000,
        "validUntil": null
      }
    ]
  }
}

Proposed signer roles

Suggested role values:

• settler: address submits or directly executes settlement
• relayer: address relays a payer-signed settlement transaction
• fee_payer: address sponsors transaction fees
• sponsor: address funds gas/fees for a settlement
• verifier: address/key signs verification artifacts
• operator: general facilitator-operated address

Proposed /settle response attribution

When settlement succeeds, facilitators SHOULD return attribution metadata.

{
  "success": true,
  "transaction": "0x123...",
  "network": "eip155:8453",
  "settledAmount": "10000",
  "facilitator": {
    "id": "cdp",
    "name": "Coinbase CDP",
    "url": "https://api.cdp.coinbase.com/platform/v2/x402",
    "settlementSigner": "0xabc...",
    "signerRole": "settler"
  },
  "attribution": {
    "extension": "facilitator-attribution",
    "version": 1,
    "paymentRequirementsHash": "0x...",
    "paymentPayloadHash": "0x...",
    "settlementTxHash": "0x123...",
    "network": "eip155:8453",
    "scheme": "exact",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xmerchant...",
    "amount": "10000"
  }
}

Optional signed attribution receipt

Facilitators MAY sign the attribution payload so observers can verify it independently.

{
  "attribution": {
    "extension": "facilitator-attribution",
    "version": 1,
    "paymentRequirementsHash": "0x...",
    "paymentPayloadHash": "0x...",
    "settlementTxHash": "0x123...",
    "network": "eip155:8453",
    "facilitatorId": "cdp",
    "settlementSigner": "0xabc...",
    "signerRole": "settler"
  },
  "signature": {
    "format": "jws",
    "kid": "did:web:api.example.com#x402-facilitator-key-1",
    "value": "header.payload.signature"
  }
}

Observer confidence guidance

Observers SHOULD treat facilitator attribution confidence roughly as:

• signed_attribution: facilitator signed attribution receipt
• settle_response: facilitator returned attribution in /settle
• supported_signer: transaction signer matched /supported.signers
• catalog_declared: resource metadata declared expected facilitator
• heuristic: inferred from address, hostname, or discovery source only

Observers SHOULD NOT treat generic payment primitive events, such as EIP-3009 AuthorizationUsed, as proof of x402 facilitator attribution without one of the stronger signals above.

Relationship to existing extensions

This is complementary to offer-receipt:

• offer-receipt proves resource-server commercial terms and delivery receipts.
• facilitator-attribution would prove which facilitator verified, sponsored, relayed, or settled the payment.

Open questions

• Should this be a standalone extension or folded into an existing receipt/attestation extension?
• Should signer role names be standardized across all schemes, or should schemes define their own role vocabularies?
• Should /supported.signers preserve backward compatibility by allowing both the current compact shape and the richer object shape?
• Should the attribution receipt use JWS only, or mirror the offer-receipt extension by supporting both JWS and EIP-712?