> ## Documentation Index
> Fetch the complete documentation index at: https://haggles.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# What is Haggles?

> HTTP 402 Payment Required for AI agents, settled on PayPal rails with double-entry micro-dollar accounting and per-agent spending policies.

**Haggles** lets any developer put a price on an HTTP endpoint (`$0.0001` to `$5.00` per call) and get paid in real USD via **PayPal** by AI agents that pay automatically within spending policies their owners control.

> [card] [Quickstart: Sell (5 min)](https://haggles.mintlify.site/quickstart-sell.md)
>
> Gate any Hono or Express route behind HTTP 402 in 2 lines of middleware and receive PayPal Payouts.

> [card] [Quickstart: Buy (5 min)](https://haggles.mintlify.site/quickstart-buy.md)
>
> Fund a prepaid wallet via PayPal Orders v2, issue a policy-capped agent key, and call paid APIs with `createHaggles`.

> [card] [Double-Entry Ledger](https://haggles.mintlify.site/concepts/ledger.md)
>
> Explore how integer micro-dollars (`$1.00 = 1,000,000` micros) and 6 ledger account kinds guarantee zero drift.

> [card] [Wire Protocol & Test Vectors](https://haggles.mintlify.site/protocol/wire-format.md)
>
> Inspect the `WWW-Authenticate: Haggles`, `Haggles-Challenge`, `Haggles-Payment`, and `Haggles-Receipt` headers.

## End-to-End Architecture & Protocol Flow

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Agent as AI Agent (@haggles/client)
    participant Seller as Seller API (@haggles/server)
    participant Fac as Haggles Facilitator (/v1/*)
    participant PP as PayPal Sandbox (Orders v2 & Payouts v1)

    Note over Agent,PP: 1. Pre-funding (One-time via Portal)
    Agent->>PP: Top up $5–$200 (PayPal Orders v2)
    PP-->>Fac: Webhook PAYMENT.CAPTURE.COMPLETED
    Fac->>Fac: Post G_PAYPAL + G_PAYPAL_FEES -> W_AVAIL

    Note over Agent,Fac: 2. Autonomous HTTP 402 Call ($0.03)
    Agent->>Seller: GET /datasets/rent-index?city=austin
    Seller-->>Agent: 402 Payment Required + Haggles-Challenge
    Agent->>Fac: POST /v1/payments (Bearer hgk_test_... + challenge)
    Fac->>Fac: Verify policy caps & lock W_AVAIL -> W_HELD (60s TTL)
    Fac-->>Agent: 201 Created (Ed25519 JWS token)

    Note over Agent,Seller: 3. Redemption & Signed Receipt
    Agent->>Seller: Retry GET + Haggles-Payment: <JWS token>
    Seller->>Fac: POST /v1/payments/:id/redeem (Bearer hgs_test_...)
    Fac->>Fac: Capture W_HELD -> S_PENDING (95%) + G_FEES (5%)
    Fac-->>Seller: 200 OK + Ed25519 JWS receipt
    Seller-->>Agent: 200 OK + Haggles-Receipt + JSON payload

    Note over Seller,PP: 4. Seller Payout Sweep (>= $1.00)
    Fac->>PP: POST /v1/payments/payouts (whole cents)
    PP-->>Fac: Webhook PAYMENT.PAYOUTS-ITEM.SUCCEEDED
```

## Why HTTP 402 + Prepaid PayPal Rails?

1. **Two-Line Seller Integration:** Protect any Hono or Express route with `@haggles/server`. Unpaid callers receive a standard `402 Payment Required` response with a machine-readable `Haggles-Challenge`.
2. **Zero-Prompt Agent Payments:** `@haggles/client` wraps `fetch`, verifies the challenge against the caller's client-side ceiling (`maxPricePerCall`), obtains a short-lived Ed25519 JWS payment token (`hgp_...`), and retries once.
3. **Hard Server-Side Guardrails:** Every agent key (`hgk_test_...`) enforces per-call, daily, and monthly USD caps, plus optional seller and hostname allowlists, inside the same serializable database transaction that locks wallet funds.
4. **Real PayPal Settlement:** Buyers fund wallets via **PayPal Orders v2**, and sellers receive earnings via **PayPal Payouts v1** (or on-demand in the Seller Studio). See [Assumptions & Limitations](https://haggles.mintlify.site/concepts/assumptions) for the full economic and regulatory design notes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.