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

# Facilitator

> Metal's hosted x402 facilitator: one URL that verifies and settles a seller's payments

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](https://docs.metalntwx.com/agents/clearing.md) |
| 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](https://docs.metalntwx.com/agents/clearing.md) 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.

```json theme={null}
{
  "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](https://docs.metalntwx.com/agents/metal-agent.md#what-a-mandate-enforces). 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](https://docs.metalntwx.com/reference/compliance/receive-policy.md) 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](https://docs.metalntwx.com/agents/clearing.md#refusals) 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`.

> [card] [Accept agent payments](https://docs.metalntwx.com/agents/quickstart-accept.md)
>
> Charge for a route in your own Express service.

> [card] [x402 on Metal](https://docs.metalntwx.com/agents/x402-on-metal.md)
>
> The payment loop and the two ways to pay.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.