API

HTTP endpoints implemented by monorepo/facilitator/index.ts

All endpoints are implemented in monorepo/facilitator/index.ts.

POST /verify

Verifies an x402 payment payload against payment requirements.

• x402 v1: routes to @x402/legacy verify

• x402 v2: routes to @x402/core facilitator verify

Request body:

{
  "paymentPayload": { "x402Version": 1 },
  "paymentRequirements": {}
}

Notes:

• The handler expects paymentPayload.x402Version to be 1 or 2.

• For v1, paymentRequirements.network must be a supported string like "base-sepolia" / "base".

• For v2, networks are CAIP-2 style like "eip155:84532".

POST /settle

Settles an x402 payment on-chain.

• x402 v1: routes to @x402/legacy settle

• x402 v2: routes to @x402/core facilitator settle (with lifecycle hooks)

Request body:

{
  "paymentPayload": { "x402Version": 2 },
  "paymentRequirements": {}
}

Notes:

• For v2, settlement can be aborted by hooks; the route returns a success:false response instead of a 500 when the abort is intentional.

POST /register

Registers an agent in ERC-8004 using an EIP-7702 authorization list and a delegation contract.

Request body (v1-style client):

{
  "x402Version": 1,
  "network": "base-sepolia",
  "agentAddress": "0x...",
  "authorization": {
    "chainId": "84532",
    "address": "0xDELEGATE_CONTRACT_ADDRESS",
    "nonce": "0",
    "yParity": 0,
    "r": "0x...",
    "s": "0x..."
  },
  "tokenURI": "ipfs://...",
  "metadata": [{ "key": "x402", "value": "..." }]
}

Notes:

• authorization.address must match DELEGATE_CONTRACT_ADDRESS (the facilitator validates this).

• authorization.chainId / authorization.nonce are serialized to strings in the example clients and deserialized back into BigInt server-side.

GET /supported

Returns supported kinds + extensions.

Response shape matches @x402/core SupportedResponse:

• kinds: a map keyed by x402 version ("1", "2", …) → array of { scheme, network }

  • This facilitator also injects v1 compatibility kinds for "base-sepolia" and "base" under "1".

• extensions: facilitator-implemented extensions (currently includes discovery and feedback)

• signers: CAIP family pattern → signer address list (for v2)

GET /health

Simple health endpoint; includes metadata like network and version.

POST /discover

Triggers an on-demand discovery crawl (stores PaymentRequired responses in a local catalog).

Request body:

{
  "seedUrls": ["https://example.com/paywalled-endpoint"],
  "maxDepth": 2,
  "maxRequests": 50,
  "timeoutMs": 10000
}

Notes:

• seedUrls is required (array of URL strings).

• Bounds are clamped server-side.

GET /catalog

Returns the current discovery catalog snapshot.

Query params:

• full=1: returns full stored PaymentRequired payloads; otherwise returns a summary view.

POST /close

Gracefully exits the process after responding. Intended for controlled environments only.