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:

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 (net + fee)
    Note over Agent: Sign two transfers:<br/>1. Net to merchant<br/>2. Fee to HivePay
    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

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

x402 payments through HivePay include the same percentage-based fee as standard checkout payments. The 402 response includes the fee breakdown:

{
  "extra": {
    "feeAccount": "hivepay",
    "feeAmount": "0.158 HBD",
    "netAmount": "10.342 HBD"
  }
}

The x402 client must sign a transaction with two transfer operations:

1. netAmount to the merchant's Hive account
2. feeAmount to HivePay's fee account

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