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

# Overview

> TypeScript SDK for adding escrow, refunds, and dispute resolution to x402 payments

<Warning>
  The X402r SDK is in active development. APIs may change between releases. Always test on Base Sepolia before using real funds on mainnet.
</Warning>

Three roles interact with the protocol:

* **Merchants** receive payments into escrow and capture funds after delivery
* **Payers** can request refunds, freeze payments, and submit evidence during disputes
* **Arbiters** verify transactions or resolve disputes (two models below)

### Two Operator Models

**Marketplace** (`deployMarketplaceOperator`): The merchant releases funds after escrow. If the payer contests, they file a refund request and an arbiter resolves it. Use this for general commerce where most transactions clear without dispute.

**Delivery Protection** (`deployDeliveryProtectionOperator`): The arbiter evaluates every transaction. The arbiter or a satisfied payer can capture funds. On a FAIL verdict, the arbiter can trigger an immediate refund. If nobody acts, funds return to the payer once escrow expires. Use this for AI content verification, schema validation, or quality checks.

See [Deploy an operator](/sdk/deploy-operator) for the full preset feature comparison, slot configurations, and deployment code.

### Packages

<CodeGroup>
  ```bash npm theme={null}
  npm install @x402r/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @x402r/sdk
  ```

  ```bash bun theme={null}
  bun add @x402r/sdk
  ```
</CodeGroup>

`@x402r/sdk` is the only package most developers need. It includes role-scoped client factories, 8 action groups (payment, escrow, refund, evidence, freeze, query, operator, watch), an `.extend()` plugin system, and ERC-8004 helpers that extract on-chain identity and reputation data from x402 extension responses.

For low-level access to contract ABIs and deploy utilities:

<CodeGroup>
  ```bash npm theme={null}
  npm install @x402r/core
  ```

  ```bash pnpm theme={null}
  pnpm add @x402r/core
  ```

  ```bash bun theme={null}
  bun add @x402r/core
  ```
</CodeGroup>

For x402 server integration:

<CodeGroup>
  ```bash npm theme={null}
  npm install @x402r/helpers
  ```

  ```bash pnpm theme={null}
  pnpm add @x402r/helpers
  ```

  ```bash bun theme={null}
  bun add @x402r/helpers
  ```
</CodeGroup>

For one-shot payments from the command line (no project install required):

<CodeGroup>
  ```bash npm theme={null}
  npx @x402r/cli pay <url> [options]
  ```

  ```bash pnpm theme={null}
  pnpm dlx @x402r/cli pay <url> [options]
  ```

  ```bash bun theme={null}
  bunx @x402r/cli pay <url> [options]
  ```
</CodeGroup>

### Guides

<CardGroup cols={2}>
  <Card title="Merchant guide" icon="store" href="/sdk/merchant/quickstart">
    Capture funds from escrow, charge directly, void, and process refunds using `createMerchantClient`.
  </Card>

  <Card title="Deploy an operator" icon="rocket" href="/sdk/deploy-operator">
    Deploy a PaymentOperator on Base or Base Sepolia and configure plugin slots.
  </Card>

  <Card title="Delivery protection" icon="shield-check" href="/sdk/delivery-protection">
    Wire merchant settlements into an arbiter that gates capture on response quality.
  </Card>

  <Card title="@x402r/cli" icon="terminal" href="/sdk/cli">
    Wallet-agnostic one-shot payments from the command line or scripts.
  </Card>
</CardGroup>

## Network support

All x402r-authored contracts use universal CREATE2 addresses: every supported chain resolves to the same address as every other supported chain.

Today, the supported chains in `@x402r/core` are **Base** and **Base Sepolia**. More EVM chains land as canonical `base/commerce-payments@v1.0.0` coverage extends.

| Chain        | Chain ID | USDC                                         |
| ------------ | -------- | -------------------------------------------- |
| Base         | `8453`   | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| Base Sepolia | `84532`  | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |

### commerce-payments v1 primitives

The `base/commerce-payments@v1.0.0` primitives ship at canonical CREATE2 addresses via CreateX permissionless salts. Each contract resolves to the same address on every supported chain.

| Contract                  | Address                                      |
| ------------------------- | -------------------------------------------- |
| `AuthCaptureEscrow`       | `0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff` |
| `ERC3009PaymentCollector` | `0x0E3dF9510de65469C4518D7843919c0b8C7A7757` |
| `Permit2PaymentCollector` | `0x992476B9Ee81d52a5BdA0622C333938D0Af0aB26` |

Salt namespace: `commerce-payments::v1::<ContractName>`.

Import the addresses from `@x402r/core`:

```ts theme={null}
import { authCaptureEscrow, tokenCollector } from '@x402r/core';

// AuthCaptureEscrow, canonical across every supported chain.
authCaptureEscrow;
// Primary token collector (currently aliases ERC3009PaymentCollector).
tokenCollector;
```

The SDK exposes these primitives on the chains listed in `@x402r/core`'s `x402rChains` (Base + Base Sepolia today). CreateX salts already reserve the CREATE2 addresses on more chains, and the registry enables each one as canonical `base/commerce-payments@v1.0.0` coverage extends.