Skip to main content

​
GX402 Facilitator

Instance: https://api.gx402.org
Purpose: verify and settle GX402 payment flows across supported networks (EVM / SVM).
Stack: Node.js, Express, TypeScript. 
https://api.gx402.org

​
Overview

The facilitator is a trusted backend service used in the GX402 payment flow. It performs three core actions:
  1. Verify — Validate that the paymentPayload satisfies paymentRequirements. This prevents invalid or poisoned payloads from being settled on-chain.
  2. Settle — Sign and submit the transaction using a configured signer (EVM or SVM).
  3. Supported — Report the payment kinds (networks, fee payers, RPCs) available on this instance.
The facilitator must run in a secure environment because it may hold private keys and perform on-chain signatures.

​
Architecture & Flow

The GX402 Facilitator acts as a secure backend layer between the client and the blockchain.
It ensures that every payment request is validated, signed, and settled under controlled conditions. The architecture consists of four main components:

​
1. Client

Any application initiating a GX402 payment:
  • Web apps
  • Mini-apps
  • Mobile apps
  • Backend services
Clients generate the paymentPayload and paymentRequirements before interacting with the facilitator.

​
2. Facilitator (api.gx402.org)

A trusted server responsible for:
  • Verifying payment payloads
  • Ensuring rules and requirements are met
  • Selecting the correct signer or connected client
  • Settling the payment on-chain
  • Reporting supported networks
It uses internal logic based on available keys and the chosen network (EVM / SVM).

​
3. Signer Layer (EVM / SVM)

Depending on the network:
  • EVM → uses EVM_PRIVATE_KEY with createSigner
  • SVM (Solana) → uses SVM_PRIVATE_KEY with createSigner
This layer is responsible for actually producing signatures required for settlement.

​
4. Blockchain RPC / Node

The facilitator communicates directly with blockchain RPC endpoints to:
  • Broadcast transactions
  • Fetch metadata
  • Validate signatures
  • Confirm settlements
EVM RPCs and SVM RPCs may be customized via environment variables.

​
Flow Overview

Below is the full lifecycle of a GX402 payment using the facilitator. 
+-----------------------+
| Client Application    |
| (Web, Mobile, Miniapp)|
+----------+------------+
           |
           | 1. Build paymentPayload + paymentRequirements
           |
           v
+-----------------------+
|  Facilitator API      |
|  POST /verify         |
+----------+------------+
           |
           | 2. Validate requirements:
           |    - amount
           |    - network
           |    - scheme
           |    - deadlines
           |    - token/symbol
           |
           v
+-----------------------+
| Verification Response |
|   { valid: true }     |
+----------+------------+
           |
           | 3. If valid → Client triggers settlement
           |
           v
+-----------------------+
|  Facilitator API      |
|  POST /settle         |
+----------+------------+
           |
           | 4. Facilitator chooses signer:
           |    - EVM: createSigner(EVM_PRIVATE_KEY)
           |    - SVM: createSigner(SVM_PRIVATE_KEY)
           |
           v
+-----------------------+
|   Blockchain RPC      |
|  (EVM / SVM Network)  |
+----------+------------+
           |
           | 5. Broadcast transaction
           | 6. Confirm & return tx hash
           |
           v
+-----------------------+
| Settlement Response   |
| { status: "confirmed",
|   signature: "0x..." }|
+-----------------------+