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

# Facilitator Introduction

> Learn about the role of an x402 facilitator

## Why use an x402 facilitator

Facilitators provide shared infrastructure for verifying and settling on-chain payments for HTTP resources using the x402 protocol. They abstract multi-chain complexity, offer a consistent API for resource servers, and enable better reliability, observability, and reuse across multiple merchants and apps.

* Consistent verification and settlement across schemes and networks
* Offload blockchain operations and complexity from resource servers
* Serve multiple merchants/apps via a stable `/verify` and `/settle` API
* Help clients discover merchants via the `/list` endpoint

## Architecture at a glance

<img src="https://mintcdn.com/payai/4LHfgOPrYQU9GWE8/images/x402-sequence-diagram.svg?fit=max&auto=format&n=4LHfgOPrYQU9GWE8&q=85&s=f9a5356f8d04bfa03987fe5a8d8d0db4" alt="x402 sequence diagram" width="1992" height="1570" data-path="images/x402-sequence-diagram.svg" />

* Client: Calls protected resources and constructs payment payloads.
* Resource Server: Advertises payment requirements, verifies/settles payments, fulfills requests.
* Facilitator Server: Verifies payment payloads and executes settlements via standard endpoints.
* Blockchain Networks: Execute and confirm payments.

### Payment flow (facilitator perspective)

From the facilitator’s point of view, the key steps of the protocol are:

1. Resource server sends a POST to the facilitator `/verify` endpoint with the Payment Payload and the Payment Requirements selected by the client.
2. Facilitator validates the payload according to the scheme and network (e.g., signatures, amounts, nonces) and returns a Verification Response.
3. When the server is ready to execute the payment, it sends a POST to the facilitator `/settle` endpoint with the Payment Payload and Payment Requirements.
4. Facilitator submits the transaction to the blockchain for the specified scheme/network, waits for confirmation, and returns a Payment Execution Response.

## Facilitator responsibilities

* Expose secure `/verify` and `/settle` endpoints that follow x402 request/response shapes
* Validate Payment Payloads per scheme and network; prevent replay and ensure idempotency
* Submit on-chain transactions for settlement and monitor confirmations
* Provide clear error responses for verification or settlement failures
* Maintain supported network coverage and RPC/wallet infrastructure
* Implement observability (logs/metrics/traces), rate limiting, retries, and alerting

## Getting started

The easiest way to connect to the PayAI facilitator is with the `@payai/facilitator` package:

```bash theme={null}
npm install @payai/facilitator
```

```typescript theme={null}
import { facilitator } from "@payai/facilitator";
import { HTTPFacilitatorClient } from "@x402/core/server";

const facilitatorClient = new HTTPFacilitatorClient(facilitator);
```

This works immediately on the **free tier** — no API keys required.

<Card title="Try the PayAI Facilitator" icon="rocket" href="https://facilitator.payai.network">
  Ready to start? Visit the PayAI Facilitator to get started.
</Card>

## API key authentication

When you're ready to scale beyond the free tier (10,000 settlements/month), create a merchant account at [merchant.payai.network](https://merchant.payai.network) to top up credits and get API keys. See [Pricing](/x402/facilitators/pricing) for details.

Set these environment variables and `@payai/facilitator` will automatically authenticate your requests:

```env theme={null}
PAYAI_API_KEY_ID=your-key-id
PAYAI_API_KEY_SECRET=your-key-secret
```

For advanced use cases, you can also pass credentials explicitly:

```typescript theme={null}
import { createFacilitatorConfig } from "@payai/facilitator";

const facilitatorClient = new HTTPFacilitatorClient(
  createFacilitatorConfig("your-key-id", "your-key-secret"),
);
```

If you need to authenticate from a language without a PayAI package, or want to understand how auth works under the hood, see the [Facilitator Authentication](/x402/facilitators/authentication) guide for the full protocol and standalone examples in TypeScript, Python, Go, and Rust.

## x402 reference

For a deeper dive into message shapes, headers, verification and settlement responses, see the <a href="/x402/reference">x402 Reference</a>.

## Need help?

<Card title="Join our Community" icon="discord" href="https://discord.gg/eWJRwMpebQ">
  Have questions or want to connect with other developers? Join our Discord server.
</Card>