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

# 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}
```

<Steps>
  <Step title="Generate timestamp">
    Get current Unix timestamp (seconds since epoch).
  </Step>

  <Step title="Sign the message">
    Sign `memoclaw-auth:{timestamp}` with your wallet's private key.
  </Step>

  <Step title="Send the header">
    Include `x-wallet-auth: {address}:{timestamp}:{signature}` in your request.
  </Step>

  <Step title="We verify">
    We cryptographically verify the signature matches the address. If valid and you have free calls remaining, the request proceeds.
  </Step>
</Steps>

### Code example

```typescript theme={null}
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

```bash theme={null}
curl https://api.memoclaw.com/v1/free-tier/info
```

<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.
</Info>

***

## x402 Payment (After Free Tier)

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

## How it works

<Steps>
  <Step title="Client sends request">
    Client sends a request to a protected route with no payment header.
  </Step>

  <Step title="Server returns 402">
    Server responds with HTTP `402 Payment Required`, including payment requirements — USDC amount and receiving address.
  </Step>

  <Step title="Client pays and retries">
    Client pays USDC on Base and retries the request with an `X-PAYMENT` header containing the signed payment proof.
  </Step>

  <Step title="Server verifies payment">
    Server verifies the payment and extracts the payer wallet address from the EIP-3009 or Permit2 payload.
  </Step>

  <Step title="Identity established">
    Server auto-creates a user if needed. Your wallet address scopes all your memories — wallet A cannot see wallet B's data.
  </Step>
</Steps>

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

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

   ```javascript theme={null}
   import { x402Fetch } from "@x402/fetch";
   ```

2. **@x402/cli** — CLI tool

   ```bash theme={null}
   npx @x402/cli pay POST https://api.memoclaw.com/v1/store --data '...'
   ```

3. **Direct signing** — Construct payment headers manually. See [x402.org/docs](https://x402.org/docs) for the full specification.

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