> ## 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.

# How it works

> The pieces of Tentacle Pay and how a payment flows from an agent to a service.

Tentacle Pay is three pieces that fit together: a **wallet** agents control, an **x402 rail** for charging over HTTP, and a **cross-chain** layer that lets a Sui balance pay services on other chains. This page explains how they connect.

## The problem

An autonomous agent that hits a paid API stalls at the paywall — it has no card, no checkout, and no human to approve the charge:

```sh theme={null}
$ curl https://api.weather.ai/forecast
HTTP/1.1 402 Payment Required
{ "error": "payment_required", "accepts": [{ "amount": "10000", "token": "USDC" }] }
```

[x402](https://x402.org) turns that `402 Payment Required` status code into a real payment handshake. The agent reads the price, signs a payment, and retries — and the request clears. Tentacle Pay runs that handshake on Sui, where stablecoins settle gasless and in under a second.

## Core concepts

<CardGroup cols={2}>
  <Card title="x402" icon="bolt">
    An open standard built on HTTP `402 Payment Required`. A server states its price; a client signs a payment; a facilitator verifies and settles it on-chain.
  </Card>

  <Card title="Facilitator" icon="shield-check">
    A hosted service that verifies signed payments and submits them to Sui. It sponsors gas and never custodies funds — settlement goes straight to the seller.
  </Card>

  <Card title="Gasless settlement" icon="gas-pump">
    Sui covers gas for stablecoin transfers natively; the facilitator sponsors the rest — sub-cent payments and any non-stablecoin coin. Agents hold only stablecoins and never pay gas.
  </Card>

  <Card title="dWallet" icon="key">
    A distributed wallet powered by [Ika](https://ika.xyz) 2PC-MPC. It signs payments for other chains using a threshold signature — no single party holds the key.
  </Card>
</CardGroup>

## Roles

* **Agent (buyer)** — a client, script, or AI agent that pays for resources. It wraps its HTTP client with the x402 SDK and signs payments with a Sui wallet.
* **Seller** — an API, MCP server, or agent that charges for a resource. It runs x402 middleware and points it at the Tentacle Pay facilitator.
* **Facilitator** — the Tentacle Pay service at `facilitator.tentaclepay.com`. It verifies payment payloads, sponsors gas, and settles on Sui.

## The x402 flow

<Steps>
  <Step title="Agent requests a resource">
    The agent makes a normal HTTP request to the seller's endpoint.
  </Step>

  <Step title="Server responds with 402">
    If payment is required, the server returns `402 Payment Required` with an `accepts` list describing the price, network, token, and recipient.
  </Step>

  <Step title="Agent signs a payment">
    The agent picks an option it supports, signs a Sui transaction authorizing the transfer, and retries the request with the signed payload attached.
  </Step>

  <Step title="Server verifies with the facilitator">
    The server forwards the payload to the facilitator's `/verify` endpoint, which checks the signature, amount, recipient, and network.
  </Step>

  <Step title="Server settles and returns the resource">
    On success the server calls `/settle`. The facilitator submits the transaction to Sui, waits for finality, and returns the transaction digest in the response headers alongside the resource.
  </Step>
</Steps>

The agent never manages gas, nonces, or RPC calls — the SDK builds the transaction and the facilitator pays for execution.

## Settling across chains

Some services live on other chains. Rather than make an agent fund a wallet per chain, Tentacle Pay lets it keep a single Sui wallet and pay outward from there.

This uses a **dWallet** — a distributed wallet whose private key is split across [Ika](https://ika.xyz)'s 2PC-MPC network, so no single party can sign alone. To pay a service on another chain, the agent:

<Steps>
  <Step title="Pays USDC on Sui">
    The agent calls the `pay_and_sign` function in the Tentacle Pay Move package, depositing USDC and asking the dWallet to sign the destination-chain payment.
  </Step>

  <Step title="Gets a verifier attestation">
    A verifier service signs an attestation bound to this exact call — protocol, signer, amount, message, and an expiry. The on-chain contract rejects the call without it.
  </Step>

  <Step title="The dWallet signs">
    The Ika coordinator produces a threshold signature over the destination-chain payment authorization, valid on that chain.
  </Step>

  <Step title="The payment settles on the destination">
    The signed authorization is submitted to the destination chain, paying the service from the dWallet — funded by the USDC the agent just paid on Sui.
  </Step>
</Steps>

The result: one wallet, one balance, any chain. See [Cross-Chain](/cross-chain/overview) for the full architecture.

## Where each piece lives

| Piece                   | What it is                                         | Repository                                                        |
| ----------------------- | -------------------------------------------------- | ----------------------------------------------------------------- |
| Wallet (`tpay`)         | The agent's CLI wallet and MCP server              | [`tentaclepay/tpay`](https://github.com/tentaclepay/tpay)         |
| `@tentaclepay/sui-x402` | The x402 SDK for Sui (client, server, facilitator) | [`tentaclepay/sui-x402`](https://github.com/tentaclepay/sui-x402) |
| Facilitator             | The hosted x402 facilitator on Sui                 | [`tentaclepay`](https://github.com/tentaclepay)                   |
| Smart contracts         | The Move package for cross-chain `pay_and_sign`    | [`tentaclepay`](https://github.com/tentaclepay)                   |

## Next steps

<CardGroup cols={2}>
  <Card title="Set up the wallet" icon="wallet" href="/wallet/get-started">
    Install `tpay` and let your agent pay for an API.
  </Card>

  <Card title="x402 overview" icon="bolt" href="/x402/overview">
    The payment rail in depth — schemes, networks, and the facilitator.
  </Card>
</CardGroup>