# 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:

+++ TypeScript
```typescript
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"
```
+++ PHP
```php
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
```bash
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
```bash
pnpm add @hiveio/x402
```
+++ npm
```bash
npm install @hiveio/x402
```
+++ yarn
```bash
yarn add @hiveio/x402
```
+++

Use `HiveX402Client` to pay for a HivePay checkout URL:

```typescript
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
```

```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](/payments/fees/)).

---

## Webhooks Still Work

When an x402 payment completes, the merchant receives the same [webhook notification](/payments/webhooks/) as with a standard checkout payment:

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

---

## Next Steps

- [Configure x402 settings for your merchant account](/x402/configuration/)
- [Build custom x402 clients for browsers and AI agents](/x402/client/)
- [Learn about fee calculations](/payments/fees/)