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

# x402 Payment Flow

> How payment-as-authentication works at the protocol level.

## Overview

The [x402 protocol](https://x402.org) turns HTTP 402 (Payment Required) into a machine-readable payment flow. Every protected MemoClaw endpoint requires a **signed payment proof** in the request header. The payment amount depends on the endpoint, and the payer's wallet address automatically becomes their user identity.

<Tip>
  Think of it like a vending machine: insert payment, get memory services. No accounts, no API keys.
</Tip>

## The flow

<Steps>
  <Step title="Request without payment">
    Client sends a request to a protected endpoint (e.g., `POST /v1/store`) without any payment header.
  </Step>

  <Step title="Server returns 402">
    Server responds with **HTTP 402** and a JSON body containing payment requirements: the exact USDC amount, the receiving wallet address, the network (Base, chain ID 8453), and the payment scheme (`exact`).
  </Step>

  <Step title="Client signs payment">
    The client signs a USDC transfer using either **EIP-3009** (`transferWithAuthorization`) or **Permit2**, then base64-encodes the signed payload.
  </Step>

  <Step title="Retry with payment header">
    Client retries the original request with the payment proof in the `X-PAYMENT` or `payment-signature` header.
  </Step>

  <Step title="Server verifies and processes">
    Server verifies the payment via the x402 facilitator, extracts the payer's wallet address from the signed payload, auto-creates or finds the user, and processes the original request.
  </Step>
</Steps>

## Wallet identity extraction

<Info>
  The payer's EVM address is extracted from the signed payment payload. For **EIP-3009** transfers, it comes from `payload.authorization.from`. For **Permit2**, from `payload.permit2Authorization.from`. This address becomes the user's identity — all memories are scoped to it.
</Info>

No registration, no API keys, no email verification. Your wallet address **is** your account.

## Per-route pricing

Only endpoints that use OpenAI (embeddings or LLM) are charged. Everything else is free.

| Endpoint                                                                                   | Price (USDC) |
| ------------------------------------------------------------------------------------------ | ------------ |
| `POST /v1/store`                                                                           | \$0.005      |
| `POST /v1/store/batch`                                                                     | \$0.04       |
| `POST /v1/recall`                                                                          | \$0.005      |
| `PATCH /v1/memories/:id`                                                                   | \$0.005      |
| `PATCH /v1/memories/batch`                                                                 | \$0.005      |
| `POST /v1/memories/extract`                                                                | \$0.01       |
| `POST /v1/memories/consolidate`                                                            | \$0.01       |
| `POST /v1/ingest`                                                                          | \$0.01       |
| `POST /v1/context`                                                                         | \$0.01       |
| `POST /v1/migrate`                                                                         | \$0.01       |
| List, get, delete, search, suggested, relations, history, graph, export, namespaces, stats | Free         |
| `GET /health`                                                                              | Free         |

All payments are in **USDC on Base** (chain ID 8453).

## Client options

There are three approaches for handling x402 payments:

### 1. @x402/fetch (recommended)

The JavaScript SDK handles the 402 → pay → retry flow automatically.

<CodeGroup>
  ```javascript JavaScript theme={null}
  import { x402Fetch } from '@x402/fetch';

  const response = await x402Fetch('https://api.memoclaw.com/v1/store', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      content: "User prefers dark mode",
      importance: 0.8
    }),
    walletPrivateKey: process.env.WALLET_PRIVATE_KEY
  });
  ```
</CodeGroup>

### 2. @x402/cli

CLI tool for manual or shell usage. Useful for testing and scripting.

### 3. Manual signing

Construct EIP-3009 or Permit2 payloads yourself. See [x402.org/docs](https://x402.org/docs) for the full specification.

## Learn more

<CardGroup cols={3}>
  <Card title="x402 Protocol" icon="link" href="https://x402.org">
    Full protocol specification and reference implementations.
  </Card>

  <Card title="Authentication" icon="lock" href="/get-started/authentication">
    Setup guide for configuring x402 payments in your agent.
  </Card>

  <Card title="Pricing" icon="tag" href="/reference/pricing">
    Complete pricing breakdown for all endpoints.
  </Card>
</CardGroup>