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

# Facilitator

> How the Tentacle Pay facilitator verifies and settles x402 payments on Sui.

The facilitator is a hosted service that does the on-chain work for x402: it verifies signed payment payloads, sponsors gas, and submits the settlement transaction to Sui. Sellers point their x402 middleware at it and never touch an RPC node.

```text theme={null}
https://facilitator.tentaclepay.com
```

It implements the standard x402 v2 facilitator interface, so any x402-compatible server library can use it.

## What it does

* **Verifies** that a payment payload is well-formed and valid for the stated requirements — signature, amount, recipient, and network.
* **Settles** by submitting the transaction to Sui and waiting for finality, then returns the transaction digest.
* **Sponsors gas** for whatever Sui's native gasless transfers don't cover — sub-cent stablecoin payments and any non-stablecoin coin — so buyers never need to hold SUI.
* **Never custodies funds.** Settlement goes directly from the buyer to the seller's `payTo` address. The facilitator only relays and pays for execution.

## Endpoints

<ParamField path="GET /" type="endpoint">
  Returns service metadata and the list of available endpoints.
</ParamField>

<ParamField path="POST /verify" type="endpoint">
  Checks a signed payment against payment requirements without settling. Body: `{ paymentPayload, paymentRequirements }`. Returns whether the payment is valid.
</ParamField>

<ParamField path="POST /settle" type="endpoint">
  Submits a verified payment to Sui and waits for finality. Body: `{ paymentPayload, paymentRequirements }`. Returns the settlement result, including the transaction digest.
</ParamField>

<ParamField path="GET /supported" type="endpoint">
  Returns the schemes, networks, and tokens the facilitator supports.
</ParamField>

In a typical integration you don't call these directly — the `HTTPFacilitatorClient` from `@x402/core/server` does it for you:

```ts theme={null}
import { HTTPFacilitatorClient } from "@x402/core/server";

const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://facilitator.tentaclepay.com",
});
```

## Supported networks

The facilitator registers the `exact` scheme for `sui:mainnet` and `sui:testnet`. See [Supported networks](/x402/supported-networks) for the full token list.

## Gas sponsoring on Sui

Gas sponsoring is how the facilitator lets buyers pay without holding SUI — and Sui's gas model makes it fit the x402 request/response flow exactly.

A Sui transaction names a **sender** and a **gas owner** separately. For a sponsored payment the buyer is the sender and the facilitator is the gas owner. Sui also supports **address-balance sponsorship**: the gas owner pays from its address balance instead of pinning specific gas coin objects. In the SDK that's an empty gas payment — `setGasPayment([])` ([Mysten docs](https://sdk.mystenlabs.com/sui/transactions/signing-and-execution#address-balance-sponsorship)).

Because no gas coin objects are baked into the signed bytes, **the buyer signs first and the facilitator co-signs the same bytes afterward** — fully asynchronous. There's no pre-flight round trip to reserve gas, no coin-object equivocation to manage, and no [Enoki](https://docs.enoki.mystenlabs.com) in the loop. It maps onto x402 one-to-one:

<Steps>
  <Step title="Facilitator advertises the sponsor">
    `/supported` returns the facilitator's `gasOwner` address and `gasBudget` in the requirements' `extra`. The facilitator can rotate across a pool of sponsor addresses to spread load.
  </Step>

  <Step title="Buyer builds and signs">
    The buyer builds a PTB that transfers the payment with `0x2::balance::send_funds`, sets itself as the sender, sets the facilitator as the gas owner, and leaves the gas payment empty. It signs the bytes and returns them in the x402 payload — without contacting the facilitator first.
  </Step>

  <Step title="Facilitator verifies">
    `/verify` checks the PTB shape — asset, amount, recipient, the advertised gas owner, and an empty gas payment — then simulates it on-chain.
  </Step>

  <Step title="Facilitator co-signs and settles">
    `/settle` signs the same bytes as the sponsor and executes with both signatures, `[buyerSignature, sponsorSignature]`. Gas is drawn from the facilitator's address balance.
  </Step>
</Steps>

<Note>
  Sui covers gas for stablecoin transfers natively, so a stablecoin payment at or above the native minimum (`0.01` of the token) carries a zero gas budget — the PTB is a lone `0x2::balance::send_funds` with `gasPrice = 0` and an empty gas payment, and there's nothing to sponsor. The facilitator's address balance covers the rest: sub-cent stablecoin payments (below `0.01`) and any non-stablecoin coin. Either way the buyer never holds SUI. See [Supported networks](/x402/supported-networks).
</Note>

## Self-hosting

The facilitator is open source and built on `@tentaclepay/sui-x402`. To run your own, register the Sui `exact` scheme on an `x402Facilitator` with a `FacilitatorSuiSigner` — the address that sponsors gas and co-signs transactions:

```ts theme={null}
import { x402Facilitator } from "@x402/core/facilitator";
import { toFacilitatorSuiSigner } from "@tentaclepay/sui-x402";
import { ExactSuiScheme } from "@tentaclepay/sui-x402/exact/facilitator";

const signer = toFacilitatorSuiSigner({
  address: "0xYourGasSponsorAddress",
  signTransaction: async (bytes) => {
    /* sign with the sponsor keypair */
  },
});

const facilitator = new x402Facilitator();
facilitator.register(["sui:mainnet", "sui:testnet"], new ExactSuiScheme(signer));
```

Fund the sponsor address's **SUI balance** so it can cover gas. Address-balance sponsorship draws from that balance, so you never select or lock individual gas coin objects — and the signer only ever signs bytes the buyer already produced, so it can run statelessly. To spread load, supply a `FacilitatorSuiSigner` whose `getAddresses()` returns several sponsor addresses; the scheme picks one per request.

Expose `/verify`, `/settle`, and `/supported` over HTTP, and point your sellers' `HTTPFacilitatorClient` at your deployment.

<Note>
  Most teams don't need to self-host. The hosted facilitator at `facilitator.tentaclepay.com` is free and covers Sui mainnet and testnet.
</Note>