Skip to main content

​
Sequence Diagram

Client                 Resource Server              Facilitator              Blockchain
  |                           |                           |                        |
  |------ GET /resource ----->|                           |                        |
  |                           |                           |                        |
  |                           |--- POST /accepts -------->|                        |
  |                           |<-- Enriched requirements -|                        |
  |                           |                           |                        |
  |<--- 402 Payment Required -|                           |                        |
  |                           |                           |                        |
  | (Client prepares payment) |                           |                        |
  |                           |                           |                        |
  |-- GET /resource + X-PAYMENT ->|                       |                        |
  |                           |                           |                        |
  |                           |--- POST /settle --------->|                        |
  |                           |                           |--- Submit tx --------->|
  |                           |                           |<-- Confirmation -------|
  |                           |<-- { success, txHash } ---|                        |
  |                           |                           |                        |
  |<----- Protected Resource -|                           |                        |
  |                           |                           |                        |

​
Key Interactions

​
Resource Server ↔ Facilitator

The resource server makes two API calls to the facilitator:
  1. POST /accepts - Retrieves enriched payment requirements before returning 402 to client
  2. POST /settle - Validates and executes payment after receiving client’s payment proof
The resource server never needs to:
  • Hold cryptocurrency or private keys
  • Understand blockchain transaction formats
  • Interact with blockchain RPC endpoints
  • Manage gas fees or transaction signing

​
Client ↔ Facilitator

The client doesn’t directly communicate with the facilitator. All interaction happens through:
  1. The 402 response body (containing enriched requirements from facilitator)
  2. The X-PAYMENT request header (containing payment proof for facilitator)
The resource server acts as a proxy, forwarding data between client and facilitator.

​
Facilitator ↔ Blockchain

The facilitator handles all transaction settlement with blockchain networks:
  • Solana: Co-signs transactions as fee payer and submits to Solana RPC
  • EVM: Calls transferWithAuthorization on token contracts and pays gas
Clients prepare signed payment proofs off-chain. Solana clients may optionally query blockchain RPC for current parameters (blockhash, token decimals) if not provided by the facilitator in the enriched requirements.