Facilitator API

The facilitator is an HTTP service with eight routes. Resource servers call POST /verify and POST /settle for every paid request. Providers register with POST /providers and list their paid routes with POST /discovery/resources. Anyone can read the supported terms and the public catalog.

You rarely call these routes by hand. The stock x402 packages (@x402/express, @x402/core) call /verify and /settle for a resource server. At start-up, the demo API and @z402-net/service-kit call checkProvider from @z402-net/server, which reads GET /providers/me. This page is the contract behind them. The wire format of the payment itself is in Protocol.

Conventions

• Base URL. The facilitator's origin, http://127.0.0.1:4022 by default. It speaks plain HTTP, so put TLS in front of it when it is reachable from outside (Run the facilitator).
• JSON. Send Content-Type: application/json. A body of another type is not read, and the route answers as it does for a body that is not a JSON object. A request body over 64 KB is refused the same way.
• Amounts are zat, as decimal strings with no sign, no leading zero and at most 16 digits, up to 2,100,000,000,000,000. Heights, confirmations and counts are JSON numbers.
• Networks are zcash:regtest, zcash:testnet or zcash:mainnet. One facilitator serves one network.
• /verify and /settle always answer HTTP 200. A refusal is in the body, as invalidReason or errorReason. Only a missing or unknown key (401), an unknown route (404) and an unforeseen failure (500) are not 200. A 4xx has no place in the x402 response schema, and a 500 would leak its body into the client's error.
• Other errors are { "error": "<code>", "message": "<text>" }. Some have no message. A wrong method on a known path is a 404, not a 405.
• No CORS headers. Browsers read the catalog through the website, which proxies the two public reads.
• Logs record the path of a request and never its query string, so what an agent searches for stays private.

Authentication

Three kinds of caller reach the facilitator, and each route says which it needs.

• The API key picks the provider. Its scheme refuses any paymentRequirements.payTo that is not that provider's. The operator's key is Z402_FACILITATOR_TOKEN. Every other provider gets a key from POST /providers.
• Key format. An issued key is z402_ followed by 43 base64url characters, 32 random bytes. Every key and token must be an RFC 6750 b64token: letters, digits and -._~+/, optionally ending in =. The word Bearer can be in any letter case, followed by one or more spaces.
• Keys are stored only as hashes, and never logged. The facilitator keeps the SHA-256 of a key. Request lines in its log name the provider id instead.
• A failed key check answers 401 with WWW-Authenticate: Bearer and the body { "error": "unauthorized" }. A key that was rotated out gets this answer from the moment it is rotated.

Routes at a glance

Read the supported terms

curl -s http://127.0.0.1:4022/supported

{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "prepaid-voucher",
      "network": "zcash:regtest",
      "extra": {
        "windowZat": "100000",
        "creditRatioBps": 2500,
        "creditCapZat": "200000",
        "zeroConfMinExpiryBlocks": 20,
        "termsVersion": "cb7f148af0fda19a"
      }
    }
  ],
  "extensions": ["bazaar"],
  "signers": { "zcash:*": [] }
}

extra carries no payTo. Each provider has its own, which you read with GET /providers/me.

Verify a payment

A request can also carry a top-level x402Version. The SDK sends it, and the facilitator reads only the one inside paymentPayload.

curl -s http://127.0.0.1:4022/verify \
  -H "authorization: Bearer $Z402_API_KEY" \
  -H 'content-type: application/json' \
  --data @verify.json

{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "resource": { "url": "http://127.0.0.1:4021/chunk" },
    "accepted": {
      "scheme": "prepaid-voucher",
      "network": "zcash:regtest",
      "asset": "ZEC",
      "amount": "500",
      "payTo": "uregtest1...",
      "maxTimeoutSeconds": 60,
      "extra": {
        "windowZat": "100000",
        "creditRatioBps": 2500,
        "creditCapZat": "200000",
        "zeroConfMinExpiryBlocks": 20,
        "termsVersion": "cb7f148af0fda19a"
      }
    },
    "payload": {
      "sessionKey": "03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8",
      "cumulativeZat": "500",
      "sig": "...128 hex characters...",
      "depositTxid": "...64 hex characters..."
    }
  },
  "paymentRequirements": {
    "scheme": "prepaid-voucher",
    "network": "zcash:regtest",
    "asset": "ZEC",
    "amount": "500",
    "payTo": "uregtest1...",
    "maxTimeoutSeconds": 60,
    "extra": {
      "windowZat": "100000",
      "creditRatioBps": 2500,
      "creditCapZat": "200000",
      "zeroConfMinExpiryBlocks": 20,
      "termsVersion": "cb7f148af0fda19a"
    }
  }
}

What it checks, in order:

1. The key names a provider, or the answer is 401.
2. The body is a JSON object whose paymentPayload and paymentRequirements fit the x402 v2 schemas (invalid_payload), and paymentPayload.x402Version is 2 (invalid_x402_version).
3. The requirements name scheme prepaid-voucher on the facilitator's network (unsupported_scheme otherwise) and fit the rail (invalid_payment_requirements): asset ZEC, payTo equal to the key's provider, amount a canonical zat from 1 to windowZat, and extra carrying exactly the rail's terms. termsVersion is not compared.
4. accepted.scheme and accepted.network equal the requirements' (invalid_scheme, invalid_network).
5. The voucher parses (invalid_payload) and its signature verifies over the scheme, network, payTo, session key and total (z402_invalid_signature).
6. The total advances by at least this call's amount (z402_cumulative_mismatch).
7. If the voucher carries a depositTxid that is new to the session, the deposit is looked up on the chain and judged. If the voucher already fits without it, the answer is valid at once and the lookup runs in the background.
8. The total does not pass the session's limit (z402_awaiting_confirmation, z402_deposit_required).

A verify waits for at most one deposit lookup, up to 30 s, and one refresh of the session, up to 5 s, before it refuses. Give the call a timeout of at least 60 s.

A valid answer names the session and carries its snapshot. The snapshot is projected as if the presented deposit were credited:

{
  "isValid": true,
  "payer": "03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8",
  "extra": {
    "session": {
      "sessionKey": "03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8",
      "cumulativeZat": "500",
      "limitZat": "100000",
      "headroomZat": "99500",
      "confirmedZat": "0",
      "pendingZat": "100000",
      "creditZat": "0",
      "tip": 214,
      "deposits": [
        {
          "txid": "...64 hex characters...",
          "valueZat": "100000",
          "status": "pending",
          "confirmations": 0,
          "expiryHeight": 254,
          "zeroConf": true
        }
      ]
    }
  }
}

A refusal has the same shape, with isValid false, a reason code and a message. Once the signature has verified, it also carries payer and extra.session, so the client can resync:

{
  "isValid": false,
  "invalidReason": "z402_deposit_required",
  "invalidMessage": "cumulativeZat 500 is over the limit 0 with nothing pending",
  "payer": "03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8",
  "extra": {
    "session": {
      "sessionKey": "03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8",
      "cumulativeZat": "0",
      "limitZat": "0",
      "headroomZat": "0",
      "confirmedZat": "0",
      "pendingZat": "0",
      "creditZat": "0",
      "tip": 214,
      "deposits": []
    }
  }
}

payer and extra.session are absent on invalid_payload, invalid_payment_requirements, invalid_network, invalid_scheme, unsupported_scheme, invalid_x402_version, z402_invalid_signature and the unexpected_* codes. Those answers come before the voucher is authenticated. Every code is in Errors and reason codes.

Settle a payment

Settle repeats the checks of verify, using only what verify or the background lookup already cached. It never waits on the chain. After the last check, in one synchronous step with no waiting in between, it appends to the ledger, commits the new total, and credits the deposit if one was resolved. Twenty concurrent settles of one voucher give exactly one success.

{
  "success": true,
  "transaction": "...64 hex characters...",
  "network": "zcash:regtest",
  "payer": "03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8",
  "amount": "500",
  "extra": { "session": { "sessionKey": "03a107bf...", "cumulativeZat": "500", "limitZat": "100000", "headroomZat": "99500", "confirmedZat": "0", "pendingZat": "100000", "creditZat": "0", "tip": 214, "deposits": [ { "txid": "...64 hex characters...", "valueZat": "100000", "status": "pending", "confirmations": 0, "expiryHeight": 254, "zeroConf": true } ] } }
}

A refused settle has success false, an errorReason, an errorMessage, an empty transaction and no amount:

{
  "success": false,
  "errorReason": "z402_cumulative_mismatch",
  "errorMessage": "cumulativeZat must be at least 1000",
  "transaction": "",
  "network": "zcash:regtest",
  "payer": "03a107bff3ce10be1d70dd18e74bc09967e4d6309ba50d5f1ddc8664125531b8",
  "extra": { "session": { "sessionKey": "03a107bf...", "cumulativeZat": "500", "limitZat": "100000", "headroomZat": "99500", "confirmedZat": "0", "pendingZat": "100000", "creditZat": "0", "tip": 214, "deposits": [ { "txid": "...64 hex characters...", "valueZat": "100000", "status": "pending", "confirmations": 0, "expiryHeight": 254, "zeroConf": true } ] } }
}

A deposit is acknowledged only by a successful settle. The facilitator never answers settlement_pending, because the SDK would call /settle again.

After a successful settle the facilitator also tells the catalog, so the item that matches the payment gets paidCallsToday plus one. A catalog error is logged and never changes the settle answer.

Register a provider

The facilitator proves that the key owns the address before it accepts either: zdecrypt owns must answer ownedByKey true and hasTransparent false. Registrations run one at a time. For a new address, the provider's runtime opens first, with its ledger lock, ledger header, replay, first poll and watcher. Only then is the registry written and the key issued.

jq '{payTo: .orchardOnlyAddress, uivk: .uivk, network: ("zcash:" + .network)}' provider.view.json |
  curl -s -X POST http://127.0.0.1:4022/providers \
    -H 'content-type: application/json' \
    --data @-

const facilitator = "http://127.0.0.1:4022";
const payTo = "uregtest1...";
const uivk = "uivkregtest1...";

const res = await fetch(`${facilitator}/providers`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    // Only when the facilitator sets Z402_REGISTRATION_TOKEN
    ...(process.env.Z402_REGISTRATION_TOKEN
      ? { authorization: `Bearer ${process.env.Z402_REGISTRATION_TOKEN}` }
      : {}),
  },
  body: JSON.stringify({ payTo, uivk, network: "zcash:regtest" }),
});
if (res.status !== 201 && res.status !== 200) {
  const refusal = (await res.json()) as { error: string; message?: string };
  throw new Error(`registration refused: ${res.status} ${refusal.error}`);
}
const { providerId, apiKey } = (await res.json()) as { providerId: string; apiKey: string };
// Store apiKey now. The facilitator shows it once and keeps only its hash.

For a new provider the answer is 201. For a registered address it is 200, with a new key, and the old key stops working at once. The answer carries Cache-Control: no-store. The viewing key is never echoed.

{
  "providerId": "3f9a1c2b4d5e6f70",
  "network": "zcash:regtest",
  "payTo": "uregtest1...",
  "apiKey": "z402_..."
}

The refusals, in the order the facilitator checks them:

Read your provider

curl -s http://127.0.0.1:4022/providers/me -H "authorization: Bearer $Z402_API_KEY"

import { checkProvider, ProviderCheckError } from "@z402-net/server";

try {
  await checkProvider({
    facilitatorUrl: "http://127.0.0.1:4022",
    token: process.env.Z402_FACILITATOR_TOKEN,
    payTo: process.env.Z402_PAY_TO ?? "",
    network: "zcash:regtest",
  });
} catch (e) {
  if (e instanceof ProviderCheckError) console.error(e.field, e.retryable);
  throw e;
}

{
  "providerId": "3f9a1c2b4d5e6f70",
  "network": "zcash:regtest",
  "payTo": "uregtest1..."
}

An unknown key, and a key that was rotated out, get 401 and { "error": "unauthorized" }. checkProvider turns each outcome into a ProviderCheckError with a field and a retryable flag. The table is in Errors and reason codes.

Declare resources

{
  "items": [
    {
      "resource": "https://md.example.com/v1/markdown",
      "type": "http",
      "x402Version": 2,
      "accepts": [
        {
          "scheme": "prepaid-voucher",
          "network": "zcash:regtest",
          "asset": "ZEC",
          "amount": "1000",
          "payTo": "uregtest1...",
          "maxTimeoutSeconds": 60,
          "extra": {
            "windowZat": "100000",
            "creditRatioBps": 2500,
            "creditCapZat": "200000",
            "zeroConfMinExpiryBlocks": 20,
            "termsVersion": "cb7f148af0fda19a"
          }
        }
      ],
      "description": "Turn a web page into clean markdown.",
      "mimeType": "application/json",
      "serviceName": "URL to markdown",
      "tags": ["markdown", "web"],
      "extensions": {
        "bazaar": { "info": { "input": { "type": "http", "method": "GET" } } },
        "z402": { "unit": "page" }
      }
    }
  ]
}

curl -s http://127.0.0.1:4022/discovery/resources \
  -H "authorization: Bearer $Z402_API_KEY" \
  -H 'content-type: application/json' \
  --data @declare.json

The answer is 200 with the items as the catalog serves them:

{
  "x402Version": 2,
  "items": [
    {
      "resource": "https://md.example.com/v1/markdown",
      "type": "http",
      "x402Version": 2,
      "accepts": [ { "scheme": "prepaid-voucher", "network": "zcash:regtest", "asset": "ZEC", "amount": "1000", "payTo": "uregtest1...", "maxTimeoutSeconds": 60, "extra": { "windowZat": "100000", "creditRatioBps": 2500, "creditCapZat": "200000", "zeroConfMinExpiryBlocks": 20, "termsVersion": "cb7f148af0fda19a" } } ],
      "lastUpdated": "2026-10-28T12:00:00.000Z",
      "description": "Turn a web page into clean markdown.",
      "mimeType": "application/json",
      "serviceName": "URL to markdown",
      "tags": ["markdown", "web"],
      "extensions": { "bazaar": { "info": { "input": { "type": "http", "method": "GET" } } }, "z402": { "unit": "page" } },
      "lastSeen": "2026-10-28T12:00:00.000Z",
      "paidCallsToday": 0
    }
  ]
}

A refusal names the item and the field. The facilitator never fetches a provider's URL, and it never echoes a value from the item:

{
  "error": "invalid_request",
  "message": "items[0].accepts[0].amount: must be a canonical zat amount from 1 to 100000",
  "index": 0
}

How the catalog treats declarations:

• It is keyed by the provider, the canonical resource and the HTTP method. The canonical resource is the URL's origin plus the bazaar.routeTemplate when that is valid, otherwise the URL's path. Two providers that list the same URL get two items, each with its own payTo.
• Declaring one service never removes another service's items.
• A provider's first declaration removes the items that came from its payments and that the declaration does not itself declare. The facilitator writes that change to disk before it answers.
• After that, the provider's settled payments only update items it declared, and never create one. A payment's resource.url and extensions.bazaar are echoed by the agent, so without this rule any payer could list a resource under a declaring provider's address for the price of one call.
• A provider that has never declared is listed from its payments, as standard x402 Bazaar facilitators do. Such an item has no lastSeen. It holds only the canonical URL, accepts built from the server's own requirements (never the accepted the agent sent), and the mimeType and bazaar extension that the payer echoed, which pass the same field checks as a declaration and nothing more. A payment never supplies a description, serviceName, tags or iconUrl.
• A provider has at most 8 such items. A payment for a ninth lists nothing, and the facilitator logs it once. A payment for a listed item still counts. A declaration is how a provider lists more, with text of its own.
• The items of the whole catalog take at most 16 MiB. A declaration that would pass that is refused whole with 400 invalid_request and the message the catalog is full, and a payment that would pass it lists nothing.

List resources

limit and offset must be non-negative decimal integers, or the answer is 400. A parameter given twice is refused. Parameters that the route does not know are ignored.

curl -s 'http://127.0.0.1:4022/discovery/resources?type=http&limit=20'

import { HTTPFacilitatorClient } from "@x402/core/server";
import { withBazaar } from "@x402/extensions/bazaar";

const bazaar = withBazaar(new HTTPFacilitatorClient({ url: "http://127.0.0.1:4022" })).extensions.bazaar;
const { items, pagination } = await bazaar.listResources({ type: "http", limit: 20 });

for (const item of items) {
  console.log(item.resource, item.accepts[0]?.amount, item.accepts[0]?.payTo);
}
console.log(`${pagination.total} items in all`);

{
  "x402Version": 2,
  "items": [ { "resource": "https://md.example.com/v1/markdown", "type": "http", "x402Version": 2, "accepts": [ { "scheme": "prepaid-voucher", "network": "zcash:regtest", "asset": "ZEC", "amount": "1000", "payTo": "uregtest1...", "maxTimeoutSeconds": 60, "extra": { "windowZat": "100000", "creditRatioBps": 2500, "creditCapZat": "200000", "zeroConfMinExpiryBlocks": 20, "termsVersion": "cb7f148af0fda19a" } } ], "lastUpdated": "2026-10-28T12:00:00.000Z", "lastSeen": "2026-10-28T12:00:20.000Z", "paidCallsToday": 12 } ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 }
}

Search resources

curl -s 'http://127.0.0.1:4022/discovery/search?query=markdown&limit=10'

{
  "x402Version": 2,
  "resources": [ { "resource": "https://md.example.com/v1/markdown", "type": "http", "x402Version": 2, "accepts": [ { "scheme": "prepaid-voucher", "network": "zcash:regtest", "asset": "ZEC", "amount": "1000", "payTo": "uregtest1...", "maxTimeoutSeconds": 60, "extra": { "windowZat": "100000", "creditRatioBps": 2500, "creditCapZat": "200000", "zeroConfMinExpiryBlocks": 20, "termsVersion": "cb7f148af0fda19a" } } ], "lastUpdated": "2026-10-28T12:00:00.000Z", "lastSeen": "2026-10-28T12:00:20.000Z", "paidCallsToday": 12 } ],
  "partialResults": false,
  "pagination": { "limit": 10, "cursor": null }
}

pagination.cursor is null on the last page. The facilitator does not need this route for discovery: the site and the demo agent read the whole list from GET /discovery/resources and filter on their own side, so nobody learns what they look for.

Objects

Payment requirements

One entry of accepts, and the paymentRequirements of a verify and a settle.

Session snapshot

extra.session in every answer after the signature verifies.

A snapshot carried by a refusal is projected and informational. Only a successful settle acknowledges a deposit.

Catalog item

The standard x402 Bazaar item, plus two fields the facilitator adds.

Limits

Past the item caps or the 16 MiB budget, a declaration for a new item is refused with a 400, and a payment does not create one. Either way the facilitator logs it once. The public routes have no rate limit.

Status codes

References

• packages/facilitator/src/app.ts: the routes, the key check and the answers.
• packages/facilitator/src/scheme.ts: verify, settle and every reason code.
• packages/facilitator/src/providers/register.ts: registration and its refusals.
• packages/facilitator/src/providers/apiKey.ts: the key format and its hash.
• packages/facilitator/src/discovery/catalog.ts: the catalog, its sources and its file.
• packages/facilitator/src/discovery/validate.ts: every rule a declaration and a query must meet.
• packages/facilitator/src/discovery/routes.ts: the three catalog routes.
• packages/server/src/provider.ts: checkProvider.
• packages/protocol/src/reasons.ts: the closed list of reason codes.
• docs/spec/protocol.md: the wire contract.
• docs/superpowers/specs/2026-10-28-z402-multi-provider-design.md: the multi-provider design, sections 4.1 to 4.4.
• x402: the standard and its Bazaar extension.
• RFC 6750: the bearer token format.