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:

Verify — Validate that the paymentPayload satisfies paymentRequirements. This prevents invalid or poisoned payloads from being settled on-chain.
Settle — Sign and submit the transaction using a configured signer (EVM or SVM).
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..." }|
+-----------------------+

Overview