@payai/facilitator

PayAI facilitator configuration for x402 TypeScript servers on Base, Solana, and supported EVM networks. For ordinary exact payments, connect to the public PayAI endpoint without a portal signup or API key within the free allowance. Add optional JWT credentials when a capability requires authentication or when you scale beyond that allowance.

Install

npm install @payai/facilitator @x402/core

Configure the merchant facilitator client

The exported facilitator object is a FacilitatorConfig that can be passed directly to the public HTTPFacilitatorClient from @x402/core/server:

import { facilitator } from "@payai/facilitator";
import { HTTPFacilitatorClient } from "@x402/core/server";

const facilitatorClient = new HTTPFacilitatorClient(facilitator);

This connects to https://facilitator.payai.network. Pass facilitatorClient to your x402 resource server, then register the payment scheme and network your route accepts.

For complete Express merchants and guarded buyers, follow the Base Mainnet guide or Solana Mainnet guide. The matching runnable examples live in PayAINetwork/docs.

Authentication and credits

Ordinary exact payments can start without an API key. New receiving wallets currently receive 1,000 free credits as a lifetime allowance; shared hosts or IP addresses also draw from a shared pool and may reach the limit sooner. Beyond that allowance, one credit is $0.001 and each settlement costs the network's on-chain gas plus 30%, converted to credits. Testnet settlements are free. Public Solana and Base batch-settlement lanes are also unauthenticated; check the live /supported response because capability-specific requirements can change.

An autonomous agent can buy a facilitator key and credits over x402 when it needs authenticated capacity. The paying wallet becomes the identity for a wallet-owned agent account; no pre-created portal account is required. A wallet already linked to a human portal account receives credits only and keeps its keys in that portal.

For authenticated use, set both variables before starting the server:

export PAYAI_API_KEY_ID=your-key-id
export PAYAI_API_KEY_SECRET=your-key-secret

facilitator reads these values when it creates request headers. With both values set, it generates and refreshes JWT bearer tokens automatically. You can also provide credentials explicitly:

import { createFacilitatorConfig } from "@payai/facilitator";
import { HTTPFacilitatorClient } from "@x402/core/server";

const facilitatorClient = new HTTPFacilitatorClient(
  createFacilitatorConfig(apiKeyId, apiKeySecret),
);

See facilitator pricing for the current allowance and credit rules. Live rates are authoritative at /pricing, and changing network and scheme support is authoritative at /supported.

Exports

• facilitator: ready-to-use config for environment-based authentication
• createFacilitatorConfig(apiKeyId?, apiKeySecret?): config with explicit or environment-based credentials
• createPayAIAuthHeaders, getOrGenerateJwt, clearJwtCache: lower-level JWT helpers