Authentication

Free tier with wallet signatures, then x402 payments. No API keys.

MemoClaw uses your wallet as identity. No API keys, no accounts. Two auth methods:

1. Free Tier — Sign a message with your wallet (100 free calls)
2. x402 Payment — Pay-per-request after free tier (automatic fallback)

---

Free Tier (Recommended Start)

Every wallet gets 100 free API calls to paid endpoints. No payment required — just prove you own a wallet.

How wallet verification works

You sign a timestamped message with your wallet’s private key. We verify the signature matches the claimed address.

Message format: memoclaw-auth:{unix_timestamp}
Header format:  x-wallet-auth: {address}:{timestamp}:{signature}

1. Generate timestamp

   Get current Unix timestamp (seconds since epoch).

2. Sign the message

   Sign memoclaw-auth:{timestamp} with your wallet’s private key.

3. Send the header

   Include x-wallet-auth: {address}:{timestamp}:{signature} in your request.

4. We verify

   We cryptographically verify the signature matches the address. If valid and you have free calls remaining, the request proceeds.

Code example

import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

async function getAuthHeader() {
  const timestamp = Math.floor(Date.now() / 1000);
  const message = `memoclaw-auth:${timestamp}`;
  const signature = await account.signMessage({ message });
  
  return `${account.address}:${timestamp}:${signature}`;
}

// Use in requests
const response = await fetch('https://api.memoclaw.com/v1/recall', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-wallet-auth': await getAuthHeader(),
  },
  body: JSON.stringify({ query: 'what did I learn today?' }),
});

// Check remaining free calls
console.log(response.headers.get('x-free-tier-remaining'));

Check your free tier status

curl https://api.memoclaw.com/v1/free-tier/info

Timestamps must be within 5 minutes of server time to prevent replay attacks. Your private key never leaves your machine — only the signature is sent.

---

x402 Payment (After Free Tier)

Once you’ve used your 100 free calls, requests automatically require x402 payment.

How it works

1. Client sends request

   Client sends a request to a protected route with no payment header.

2. Server returns 402

   Server responds with HTTP 402 Payment Required, including payment requirements — USDC amount and receiving address.

3. Client pays and retries

   Client pays USDC on Base and retries the request with an X-PAYMENT header containing the signed payment proof.

4. Server verifies payment

   Server verifies the payment and extracts the payer wallet address from the EIP-3009 or Permit2 payload.

5. Identity established

   Server auto-creates a user if needed. Your wallet address scopes all your memories — wallet A cannot see wallet B’s data.

Your wallet address is extracted from the payment proof. It becomes your user identity and scopes all your memories. No registration needed.

Payment methods

Two EVM payment signature types are supported:

• EIP-3009 — transferWithAuthorization
• Permit2 — Uniswap’s permit-based transfer

Both are automatically handled by x402-compatible clients. You don’t need to choose between them.

Making authenticated requests

Three options for making authenticated requests:

1. @x402/fetch — JavaScript SDK

   import { x402Fetch } from "@x402/fetch";
   

2. @x402/cli — CLI tool

   npx @x402/cli pay POST https://api.memoclaw.com/v1/store --data '...'
   

3. Direct signing — Construct payment headers manually. See x402.org/docs for the full specification.

You need a wallet with USDC on Base network (chain ID 8453). Get USDC from any exchange that supports Base.