# x402 Protocol

Accept automated HBD payments from AI agents and x402-aware clients through your existing HivePay checkout URLs.

---

## What is x402?

x402 is an open protocol that brings native payments to the web using the HTTP [402 Payment Required](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/402) status code. When a client requests a paid resource, the server responds with `402` and payment instructions. The client signs a payment, retries the request, and gets access.

No accounts. No API keys on the client side. No credit card forms. Just HTTP and a signed blockchain transaction.

The protocol was [launched by Coinbase](https://github.com/coinbase/x402) with Cloudflare as a foundation partner, and is Apache-2.0 licensed. The Hive implementation is built by [Ecency](https://ecency.com) and published as [`@hiveio/x402`](https://www.npmjs.com/package/@hiveio/x402).

---

## Why Hive + HBD?

Hive is a natural fit for x402 micropayments:

| Property | Benefit |
|----------|---------|
| **No on-chain gas** | Every micropayment arrives in full — Hive has no gas, and HivePay does not deduct anything from individual transactions either |
| **3-second finality** | Near-instant settlement, no waiting for confirmations |
| **HBD stablecoin** | Pegged to $1 USD — no volatility risk for service providers |
| **Human-readable accounts** | `alice` pays `your-service`, not `0x742d35Cc...` |
| **Battle-tested** | Billions of transactions processed since 2016 |

---

## How It Works with HivePay

HivePay integrates x402 directly into the existing payment session flow. When a merchant creates a payment via the API, the returned checkout URL (`/for/[slug]`) works for both human users (browser checkout) and automated clients (x402 protocol).

```mermaid
sequenceDiagram
    participant Agent as AI Agent / x402 Client
    participant HivePay as HivePay (/for/[slug])
    participant Hive as Hive Blockchain
    participant Merchant as Merchant Server

    Merchant->>HivePay: Create payment session (API)
    HivePay-->>Merchant: { checkoutUrl: "/for/abc123" }
    Merchant-->>Agent: Share checkout URL

    Agent->>HivePay: GET /for/abc123
    HivePay-->>Agent: 402 + payment requirements (full amount to merchant)
    Note over Agent: Sign one transfer:<br/>full amount to merchant
    Agent->>HivePay: GET /for/abc123 + x-payment header
    HivePay->>Hive: Verify signature & broadcast
    Hive-->>HivePay: Confirmed (txId, block)
    HivePay-->>Agent: 200 OK + settlement details
    HivePay->>Merchant: Webhook notification (completed)
```

### Key Differences from Generic x402

| Aspect | Generic x402 | HivePay x402 |
|--------|-------------|--------------|
| **Entry point** | Any endpoint with `paywall()` middleware | HivePay checkout URL (`/for/[slug]`) |
| **Transaction shape** | Single transfer to one recipient | Single transfer of the full session amount to the merchant |
| **Session tracking** | None — stateless | Full session lifecycle with status tracking |
| **Webhooks** | None | Merchant receives webhook on completion |
| **Audit trail** | None | Full audit logging |

---

## Client Detection

HivePay automatically detects x402-aware clients (AI agents, `HiveX402Client`, CLI tools) by inspecting the request:

- If the `x-payment` header is present — it's an x402 payment retry
- If the `Accept` header does not include `text/html` — it's not a browser

Browser users see the normal checkout page. x402 clients get a `402` response with payment requirements.

---

## Fees

HivePay does not deduct anything from individual x402 payments. The full session amount goes to the merchant in a single Hive transfer. Merchants are billed monthly for processed volume — see [Billing](/payments/fees/).

```json
{
  "scheme": "exact",
  "network": "hive:mainnet",
  "maxAmountRequired": "10500",
  "payTo": "merchant-account",
  "asset": "HBD"
}
```

The x402 client signs a transaction with a single `transfer_operation` of the full amount to `payTo`.

---

## Merchant Control

x402 is **enabled by default** for all merchants. Merchants can disable it in the [Dashboard settings](/dashboard/settings/) or via API. When disabled, x402 clients receive a `403` error on the checkout URL.

---

## Guides

[!ref icon="rocket" text="Quick Start"](/x402/quick-start/)
[!ref icon="gear" text="Merchant Configuration"](/x402/configuration/)
[!ref icon="code" text="Client Integration"](/x402/client/)