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

# X402 Protocol Overview

> How x402r extends the x402 HTTP payment protocol with escrow capabilities

## What is X402?

**X402** is an HTTP payment protocol that uses the `402 Payment Required` status code to enable machine-to-machine payments. It allows servers to request payment from clients using standardized headers and payload formats.

Think of it as "Stripe for the programmable internet" - agents, robots, and autonomous systems can pay for API access, compute time, or any HTTP resource.

## Payment Schemes

X402 v2 supports two payment schemes:

<CardGroup cols={2}>
  <Card title="exact" icon="bolt">
    Immediate settlement - payment clears the moment the client sends the request.

    **Best for:** Simple purchases, low-value transactions, trusted services
  </Card>

  <Card title="escrow" icon="lock">
    Deferred settlement - funds stay locked until conditions clear.

    **Best for:** High-value transactions, usage-based billing, long-running tasks
  </Card>
</CardGroup>

## Why Escrow

The `exact` scheme works well for immediate-delivery payments, but creates friction for:

### High-Value Transactions

**Problem:** No recourse if service fails after payment

```
Client pays $500 → Server crashes → Money lost
```

**Escrow Solution:** Escrow holds funds until the captureAuthorizer verifies the work

```
Client authorizes $500 → Work completes → Operator releases → Server receives
```

### Variable Pricing

**Problem:** Usage-based billing requires estimating upfront

Consider an LLM agent making API calls:

* Unknown final cost (depends on tokens used)
* Can't pay exact amount in advance
* Server needs guarantee of payment

**Escrow Solution:** Lock a max amount, capture actual usage

```
Client authorizes $10 → Uses $6.50 → Operator captures $6.50 → Refund $3.50
```

### Long-Running Tasks

**Problem:** Work takes hours or days to complete

```
Client pays for video rendering → 48 hours later → How to verify completion?
```

**Escrow Solution:** Conditional capture with verification

```
Client authorizes → Work progresses → Client verifies → Capture on approval
```

### Multi-Request Sessions

**Problem:** Signing 1,000 individual requests is impractical

```
Agent makes 1,000 API calls at $0.01 each
= 1,000 signatures + 1,000 on-chain transactions
```

**Escrow Solution:** One authorization, many captures

```
Client authorizes $10 once → Server tracks usage → Server batches captures on a schedule
```

## How x402r Extends X402

x402r provides the **auth-capture scheme implementation** for x402:

1. **Base Commerce Payments Integration**
   * Audited escrow contracts from Base
   * Auth/capture pattern for deferred settlement
   * On-chain safety guarantees

2. **Operator Contracts**
   * Conditional capture logic
   * Dispute resolution
   * Fee distribution
   * Time-based capture

3. **Payment Facilitator**
   * Validates ERC-3009 signatures
   * Settles authorizations on-chain
   * Tracks payment state

4. **Developer Tools**
   * TypeScript SDK
   * Deployment scripts
   * Example implementations

## Payment Flow

The auth-capture scheme is two-phase: the facilitator first authorizes (locks the client's signed funds in escrow at the 402 settlement), then later captures to the receiver or voids back to the payer per policy. For the full HTTP and on-chain sequence diagrams, see the [auth-capture flow](/x402-integration/auth-capture) and the [on-chain payment sequence](/contracts/architecture#payment-flow-sequence).

## Use Cases

<AccordionGroup>
  <Accordion title="AI Agent API Access">
    LLM agent needs to call external APIs with variable token costs.

    **Flow:**

    1. Agent authorizes \$20 max
    2. Makes 50 API calls totaling \$12.50
    3. Server captures \$12.50
    4. Agent reclaims unused \$7.50
  </Accordion>

  <Accordion title="Compute Marketplace">
    Client needs GPU cluster for training job.

    **Flow:**

    1. Client authorizes \$500 for 48-hour job
    2. Training completes in 36 hours (\$375)
    3. Client verifies results
    4. Operator releases $375, refunds $125
  </Accordion>

  <Accordion title="Data Access Sessions">
    Application needs access to real-time data feed.

    **Flow:**

    1. App authorizes \$100 for monthly access
    2. Provider streams data
    3. Provider captures \$3.33 daily (30-day billing)
    4. Automatic refund if service interrupted
  </Accordion>

  <Accordion title="Freelance Services">
    Client hires developer for project work.

    **Flow:**

    1. Client authorizes \$2000 in escrow
    2. Developer completes milestones
    3. Arbiter verifies each milestone
    4. Operator releases payment on approval
    5. Dispute resolution if disagreement
  </Accordion>
</AccordionGroup>

## Key Concepts

### Authorization

Lock funds in escrow without immediate transfer. Client signs an ERC-3009 authorization allowing the escrow contract to pull tokens.

### Capture

Capture authorized funds to the receiver. The operator contract decides when and how much to capture based on configured conditions.

### Void

Return funds to payer before capture. Used for full refunds during the escrow period.

### Reclaim

Safety valve for payer. If authorization expires without capture, payer can reclaim funds directly from escrow.

### Operator

Smart contract that controls capture/void logic. Different operators enable different payment patterns:

* **Time-locked**: Capture after period expires
* **Arbiter-controlled**: Third party decides capture
* **Usage-based**: Capture proportional to consumption
* **Immediate**: Behaves like `exact` scheme

## Next Steps

<CardGroup cols={2}>
  <Card title="auth-capture Scheme Spec" icon="file-contract" href="/x402-integration/auth-capture">
    Complete technical specification for the auth-capture payment scheme.
  </Card>

  <Card title="Smart Contracts" icon="code" href="/contracts/overview">
    Understand the escrow and operator contracts.
  </Card>

  <Card title="SDK Overview" icon="rocket" href="/sdk/overview">
    Get started building with x402r.
  </Card>
</CardGroup>