Docs
Powered by

Quick Start

Accept automated x402 payments from AI agents through your existing HivePay integration — no additional server-side setup needed.

Overview

If you already have a HivePay integration that creates payment sessions and returns checkout URLs, x402 support is automatic. AI agents and x402-aware clients can pay using the same checkout URL that human users visit in their browser.

Merchant Side (No Changes Needed)

Your existing payment creation code already works with x402:

import { HivePay } from '@hivepay/client';

const hivepay = new HivePay({ apiKey: 'sk_live_xxx' });

const payment = await hivepay.payments.create({
  amount: '10500',          // 10.500 HBD
  currency: 'HBD',
  description: 'API access'
});

// This URL works for BOTH browsers and x402 clients
const checkoutUrl = payment.checkoutUrl;
// e.g., "https://hivepay.me/for/api-access-a1b2c3"
 
use HivePay\HivePay;

$hivepay = new HivePay(['apiKey' => 'sk_live_xxx']);

$payment = $hivepay->payments->create([
    'amount' => '10500',          // 10.500 HBD
    'currency' => 'HBD',
    'description' => 'API access',
]);

// This URL works for BOTH browsers and x402 clients
$checkoutUrl = $payment['checkoutUrl'];
// e.g., "https://hivepay.me/for/api-access-a1b2c3"
 
curl -X POST https://hivepay.me/api/public/payments/create \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10500",
    "currency": "HBD",
    "description": "API access"
  }'

When a browser visits the checkout URL, they see the normal payment page. When an x402 client visits the same URL, they receive a 402 response and can pay automatically.

Client Side (AI Agent)

Install the Hive x402 client library:

pnpm add @hiveio/x402
 
npm install @hiveio/x402
 
yarn add @hiveio/x402

Use HiveX402Client to pay for a HivePay checkout URL:

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

const client = new HiveX402Client({
  account: 'alice',
  activeKey: '5K...',   // Hive active private key (WIF format)
  maxPayment: 15.0      // Max HBD per request (safety limit)
});

// Pay for a HivePay checkout URL
const response = await client.fetch('https://hivepay.me/for/api-access-a1b2c3');
const data = await response.json();

console.log(data);
// {
//   success: true,
//   txId: "abc123...",
//   payer: "alice",
//   sessionId: "cmj7b2rg10004d2rimvum8kaz",
//   status: "completed"
// }

The client transparently handles the full flow:

  1. GET /for/api-access-a1b2c3 — receives 402 with payment requirements
  2. Signs two HBD transfers (net to merchant + fee to HivePay)
  3. Retries with the x-payment header containing the signed payload
  4. Receives settlement confirmation

What the 402 Response Looks Like

When an x402 client hits a checkout URL without a payment header:

HTTP/1.1 402 Payment Required
x-payment: <base64-encoded payment requirements>
Content-Type: application/json
{
  "x402Version": 1,
  "accepts": [{
    "x402Version": 1,
    "scheme": "exact",
    "network": "hive:mainnet",
    "maxAmountRequired": "10.500 HBD",
    "resource": "/for/api-access-a1b2c3",
    "payTo": "merchant-account",
    "validBefore": "2025-01-15T11:30:00.000Z",
    "description": "API access",
    "extra": {
      "sessionId": "cmj7b2rg10004d2rimvum8kaz",
      "feeAccount": "hivepay",
      "feeAmount": "0.158 HBD",
      "netAmount": "10.342 HBD"
    }
  }]
}

The extra field tells the client the fee breakdown. The signed transaction must include two transfers matching the netAmount and feeAmount.

Webhooks Still Work

When an x402 payment completes, the merchant receives the same webhook notification as with a standard checkout payment:

{
  "type": "payment.status_changed",
  "data": {
    "id": "cmj7b2rg10004d2rimvum8kaz",
    "merchantId": "cmkfgjmim00008rcxp81upef9",
    "status": "completed",
    "providerId": "hive",
    "internalId": "abc123..."
  }
}

Next Steps

HivePay © 2026