Skip to main content

​
Overview

The x402 protocol 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.
Think of it like a vending machine: insert payment, get memory services. No accounts, no API keys.

​
The flow

1

Request without payment

Client sends a request to a protected endpoint (e.g., POST /v1/store) without any payment header.
2

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).
3

Client signs payment

The client signs a USDC transfer using either EIP-3009 (transferWithAuthorization) or Permit2, then base64-encodes the signed payload.
4

Retry with payment header

Client retries the original request with the payment proof in the X-PAYMENT or payment-signature header.
5

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.

​
Wallet identity extraction

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.
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.
EndpointPrice (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, statsFree
GET /healthFree
All payments are in USDC on Base (chain ID 8453).

​
Client options

There are three approaches for handling x402 payments: The JavaScript SDK handles the 402 → pay → retry flow automatically. 
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
});

​
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 for the full specification.

​
Learn more

x402 Protocol

Full protocol specification and reference implementations.

Authentication

Setup guide for configuring x402 payments in your agent.

Pricing

Complete pricing breakdown for all endpoints.