@hiveio/x402

Hive/HBD-native implementation of the x402 payment standard. Enables HTTP 402 micropayments using Hive's zero-fee stablecoin HBD (Hive Backed Dollars).

How it works

Client                    API Server                Facilitator          Hive
  |  GET /premium           |                          |                  |
  |------------------------>|                          |                  |
  |  402 + x-payment header |                          |                  |
  |<------------------------|                          |                  |
  |  sign HBD transfer      |                          |                  |
  |  GET /premium + x-payment                          |                  |
  |------------------------>|  POST /verify            |                  |
  |                         |------------------------->|  verify sig      |
  |                         |  { isValid: true }       |----------------->|
  |                         |<-------------------------|                  |
  |                         |  POST /settle            |                  |
  |                         |------------------------->|  broadcast tx    |
  |                         |  { success, txId }       |----------------->|
  |                         |<-------------------------|                  |
  |  200 + resource data    |                          |                  |
  |<------------------------|                          |                  |

Install

npm install @hiveio/x402

Quick start

1. Start the facilitator

import { createFacilitator } from "@hiveio/x402/facilitator";

const app = createFacilitator();
app.listen(4020);

2. Add paywall to your API (Express)

import express from "express";
import { paywall } from "@hiveio/x402/middleware";

const app = express();

app.get("/api/premium", paywall({
  amount: "0.050 HBD",
  receivingAccount: "your-hive-account",
  facilitatorUrl: "http://localhost:4020",
}), (req, res) => {
  res.json({ data: "premium content", payer: req.payer });
});

app.listen(3000);

3. Add paywall to your API (Next.js App Router)

// app/api/premium/route.ts
import { withPaywall } from "@hiveio/x402/middleware/nextjs";

async function handler(req: Request, ctx: { payer: string; txId: string }) {
  return Response.json({ data: "premium content", payer: ctx.payer });
}

export const GET = withPaywall({
  amount: "0.050 HBD",
  receivingAccount: "your-hive-account",
  facilitatorUrl: "http://localhost:4020",
}, handler);

4. Add paywall to your API (Hono)

import { Hono } from "hono";
import { honoPaywall } from "@hiveio/x402/middleware/hono";

const app = new Hono();

app.get("/api/premium", honoPaywall({
  amount: "0.050 HBD",
  receivingAccount: "your-hive-account",
  facilitatorUrl: "http://localhost:4020",
}), (c) => {
  return c.json({ data: "premium content", payer: c.get("payer") });
});

export default app;

5. Pay for content (AI agent / client)

import { HiveX402Client } from "@hiveio/x402/client";

const client = new HiveX402Client({
  account: "alice",
  activeKey: "5K...",    // Hive active private key (WIF)
  maxPayment: 0.1,       // max HBD per request
});

const res = await client.fetch("http://localhost:3000/api/premium");
const data = await res.json();

Subpath exports

Import	Description
@hiveio/x402/types	Constants, types, encode/decode utilities
@hiveio/x402/facilitator	Facilitator service (verify + settle + nonce stores)
@hiveio/x402/client	HiveX402Client fetch wrapper for paying agents
@hiveio/x402/middleware	Express paywall() middleware
@hiveio/x402/middleware/nextjs	Next.js withPaywall() route wrapper
@hiveio/x402/middleware/hono	Hono honoPaywall() middleware

Facilitator

The facilitator verifies secp256k1 signatures against Hive accounts' on-chain active public keys and broadcasts HBD transfers.

import { createFacilitator } from "@hiveio/x402/facilitator";

const app = createFacilitator({
  // All options are optional:
  dbPath: "nonces.db",           // SQLite path (default)
  nonceStore: customStore,       // or provide your own NonceStore
  rateLimit: { max: 60, windowMs: 60_000 },  // rate limiting (enabled by default)
});

Endpoints

Method	Path	Description
GET	/health	Health check
GET	/supported-networks	Returns ["hive:mainnet"]
POST	/verify	Verify a signed payment
POST	/settle	Verify + broadcast + mark nonce spent

Nonce stores

SQLite (default, zero-config):

import { SqliteNonceStore } from "@hiveio/x402/facilitator";
const store = new SqliteNonceStore("nonces.db"); // or ":memory:"

Redis (production):

import { RedisNonceStore } from "@hiveio/x402/facilitator";
import Redis from "ioredis";

const store = new RedisNonceStore({
  client: new Redis(),
  prefix: "x402:nonce:",    // default
  ttlSeconds: 86400,        // default: 24 hours
});

Client

import { HiveX402Client } from "@hiveio/x402/client";

const client = new HiveX402Client({
  account: "alice",
  activeKey: "5K...",
  maxPayment: 1.0,  // max HBD per request (default: 1.000)
});

// Transparently handles 402 → sign → retry
const response = await client.fetch("https://api.example.com/premium");

Lower-level API

import { signPayment, parseRequirements } from "@hiveio/x402/client";

// Parse requirements from a 402 response
const requirements = parseRequirements(response);

// Sign a payment (returns base64-encoded x-payment header value)
const header = await signPayment({
  account: "alice",
  activeKey: "5K...",
  requirements,
});

Browser-compatible building blocks

For browser-based signing (e.g. Hive Keychain, HiveAuth), use buildPaymentTransaction + encodePaymentPayload instead of signPayment:

import { buildPaymentTransaction, encodePaymentPayload } from "@hiveio/x402/client";

// 1. Build unsigned transaction (uses Web Crypto, no Node.js deps)
const { transaction, nonce } = await buildPaymentTransaction({
  account: "alice",
  requirements,
});

// 2. Sign with your preferred method (Keychain, HiveAuth, etc.)
const signedTx = await yourSigner(transaction);

// 3. Encode into x-payment header
const header = encodePaymentPayload({ signedTransaction: signedTx, nonce });

Types

import type {
  PaymentRequirements,
  PaymentRequired,
  PaymentPayload,
  VerifyRequest,
  VerifyResponse,
  SettleRequest,
  SettleResponse,
  NonceStore,
} from "@hiveio/x402/types";

import {
  encodePayment,
  decodePayment,
  formatHBD,     // formatHBD(0.05) → "0.050 HBD"
  parseHBD,      // parseHBD("0.050 HBD") → 0.05
  X402_VERSION,  // 1
  HIVE_NETWORK,  // "hive:mainnet"
} from "@hiveio/x402/types";

Why Hive + HBD?

• Zero fees: Hive has no transaction fees — every micropayment arrives in full
• 3-second finality: Blocks every 3 seconds, no waiting for confirmations
• Stable value: HBD is an algorithmic stablecoin pegged to $1 USD
• Built-in accounts: Human-readable account names (no hex addresses)
• Battle-tested: Hive has processed billions of transactions since 2016

License

MIT