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 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 with Cloudflare as a foundation partner, and is Apache-2.0 licensed. The Hive implementation is built by Ecency and published as @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).

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.

{
  "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 or via API. When disabled, x402 clients receive a 403 error on the checkout URL.

Guides

Quick Start

quick-start/

Merchant Configuration

configuration/

Client Integration

client/