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 a single HBD transfer of the full amount to the merchant
  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"
    }
  }]
}

The signed transaction must contain exactly one transfer_operation of maxAmountRequired to payTo (the merchant). HivePay does not collect a per-transaction cut — billing happens monthly based on processed volume (see Billing).

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