Facilitator

Metal’s facilitator verifies a seller’s x402 payments and settles them, paying the gas. The official x402 middleware makes every call below for you.


Base URL	`https://x402-testnet.metalntwx.com/x402/facilitator`
In code	`METAL_NETWORKS.testnet.facilitatorUrl` from `@metalntwx/metal-pay`
Network	`eip155:63825`
Token	`*USDZ`, `0x000000000000000000000000000000000000B5d5`, 18 decimals
EIP-712 domain	`USD Zero`, version `1`
Schemes	`exact`, and `bajillion` to pay per call
Authentication and cost	None

Endpoints

Endpoint	Does
`GET /supported`	Lists the networks and schemes it settles.
`POST /verify`	Says whether a signed payment would settle, by simulating the transfer at the chain’s clock. Sends nothing.
`POST /settle`	Repeats the checks, submits the transfer on chain from its own account, paying the gas, and waits up to 60 seconds for the receipt.
`GET /settlements`	Lists the payments settled to an address or a clearing key.
`GET /readyz`	Says whether the facilitator can reach the chain and its clearing service; `503` with `rpc_unreachable` or `clearing_unavailable` when not. Served at the host’s root, outside the base URL.

/verify and /settle take the x402 payment and the offer it answers, and answer 200 with the standard x402 result. A /settle answer also carries extra.settlement, with the payment’s id and first, which is true only for the request that claimed the payment: deliver on that one. For a clearing payment, transaction is empty and extra.clearing carries the receipt.

GET /settlements

GET /settlements?payTo=<address or clearing key>&since=<ms> lists the payments settled to it at or after since, oldest first, 500 to a page; pass the last row’s settledAt as the next since. The listing is public.

{
  "settlements": [
    {
      "id": "<payment id>",
      "network": "eip155:63825",
      "scheme": "exact",
      "payer": "<payer address>",
      "payTo": "<payee address>",
      "amount": "10000000000000000",
      "transaction": "<transaction hash>",
      "settledAt": 1791224477542
    }
  ]
}

Limits

Endpoint	Limit	Past it
`/verify`	600 requests a minute from one IP address	`429`, `rate_limited`
`/settle`	1,200 requests a minute from one IP address	`429`, `rate_limited`
`GET /settlements`	60 requests a minute from one IP address	`429`, `rate_limited`
`/verify`, `/settle`	Request bodies up to 1 MiB	`413`, `payload_too_large`
`/settle`	120 settlements a minute, counted against the `payTo`, or against the payer for a payment under a cent	`429`, `rate_limited`
`/settle`	1,000 settlements in 24 hours, counted the same way	`daily_limit_reached`
`/settle`	10 transfers from one payer, in flight or reverted in the last ten minutes	`429`, `rate_limited`
`/settle`	56 transfers waiting to be sent or for a receipt, across all sellers	`429`, `rate_limited`

The limits on settlements count exact settlements that were sent and did not revert; a clearing payment counts only toward the per-IP limits. Anyone can pay any payTo, so other people’s payments to your address count toward its limits too. If your payTo reaches its daily limit, receive at a new address.

Refusal reasons

/verify returns the reason as invalidReason and /settle as errorReason; the middleware passes it to the payer in its 402.

Reason	Meaning
`unsupported_network`, `unsupported_scheme`, `unsupported_asset`, `unsupported_x402_version`	The offer asks for something the facilitator does not settle.
`invalid_payload`, `payment_mismatch:<field>`	The payment is malformed, or differs from the offer in the field named.
`bad_signature`	The signature is not the payer’s. The message names the signing domain the token expects.
`authorization_window`	The payment is not valid at the chain’s current time.
`transfer_would_fail`	The token would refuse the transfer: balance, or a used nonce.
`mandate_*`	The payer’s account refuses the payment under its mandate. The first answer for one refused when its transaction ran names that transaction.
`rpc_unreachable`, `rate_limited`, `daily_limit_reached`	Nothing moved. Retry later.
`already_settled`	This payment settled before. For `exact`, in the transaction named: treat it as paid once. For clearing, the receipt is recorded before the seller’s handler runs, so it is served at most once.
`nonce_already_used`	The payer used this authorization elsewhere. Do not deliver.
`payment_in_flight`	Another request is settling this payment. Retry shortly.
`payment_failed`, `payment_reverted`	The transfer reverted or was never sent; `payment_failed` names the transaction a revert spent gas in. The payer signs a new one.
`recipient_refuses`	The payee’s receive policy refuses this payment, named in the message. Nothing was sent.
`payment_quarantined`	The payee’s receive policy refused the payment at inclusion and the token sent it to escrow, in the transaction named. The authorization is spent and the payee was not paid. Do not deliver.
`settlement_in_doubt`	The transfer may have been sent, and no receipt came within 60 seconds. Retry `/settle`, or look the transaction up; it is never sent a second time.
`invalid_clearing_payment`, `payment_already_used`	A clearing payment does not check out, or its receipt settled for another seller or under another reference.

A second /settle for the same payment sends nothing and answers already_settled, with the first transaction for an exact payment. Anyone holding a payment can present it, and once sent it is public on chain, so the same payment can arrive in several requests; deliver only on the one whose extra.settlement.first is true.

Accept agent payments

Charge for a route in your own Express service.

x402 on Metal

The payment loop and the two ways to pay.

Start

Pay

Accept

Reference

Network

Endpoints

GET /settlements

Limits

Refusal reasons

Accept agent payments

x402 on Metal

​Endpoints

​GET /settlements

​Limits

​Refusal reasons

Accept agent payments

x402 on Metal

Endpoints

GET /settlements

Limits

Refusal reasons