> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gx402.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Facilitator

> Comprehensive, production-ready documentation for the GX402 Facilitator architecture, endpoints, request/response schemas, examples, deployment, security, and troubleshooting.

# GX402 Facilitator

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

***

```txt theme={null}
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.

```txt theme={null}
+-----------------------+
| 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..." }|
+-----------------------+
```