Session Auth

POST /auth/session — Exchange a wallet signature for a JWT session token.

POST /auth/session

Session Auth

cURL

curl --request POST \
  --url https://api.memoclaw.com/auth/session \
  --header 'Content-Type: application/json' \
  --data '
{
  "address": "<string>",
  "timestamp": 123,
  "signature": "<string>"
}
'

import requests

url = "https://api.memoclaw.com/auth/session"

payload = {
    "address": "<string>",
    "timestamp": 123,
    "signature": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({address: '<string>', timestamp: 123, signature: '<string>'})
};

fetch('https://api.memoclaw.com/auth/session', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.memoclaw.com/auth/session",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'address' => '<string>',
    'timestamp' => 123,
    'signature' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.memoclaw.com/auth/session"

	payload := strings.NewReader("{\n  \"address\": \"<string>\",\n  \"timestamp\": 123,\n  \"signature\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.memoclaw.com/auth/session")
  .header("Content-Type", "application/json")
  .body("{\n  \"address\": \"<string>\",\n  \"timestamp\": 123,\n  \"signature\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.memoclaw.com/auth/session")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"address\": \"<string>\",\n  \"timestamp\": 123,\n  \"signature\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

200

{
  "token": "<string>",
  "wallet": "<string>",
  "expires_at": "<string>"
}

This endpoint is free and does not require x402 payment.

Session auth lets you sign once with your wallet and use a JWT token for subsequent requests. This avoids signing every request individually and is used by the MemoClaw dashboard.

Request Body

address · string · required

Your EVM wallet address.

timestamp · number · required

Current Unix timestamp (seconds). Must be within 5 minutes of server time.

signature · string · required

Signature of the message memoclaw-auth:{timestamp} signed with your wallet’s private key.

Response (200)

token · string

JWT session token. Valid for 7 days. Include as Authorization: Bearer {token} in subsequent requests.

wallet · string

Your wallet address.

expires_at · string

ISO 8601 expiry timestamp for the token.

Example

curl

curl -X POST https://api.memoclaw.com/auth/session \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "timestamp": 1707800000,
    "signature": "0x..."
  }'

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const timestamp = Math.floor(Date.now() / 1000);
const message = `memoclaw-auth:${timestamp}`;
const signature = await account.signMessage({ message });

const response = await fetch("https://api.memoclaw.com/auth/session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    address: account.address,
    timestamp,
    signature,
  }),
});

const { token } = await response.json();

// Use the token for subsequent requests
const memories = await fetch("https://api.memoclaw.com/v1/memories", {
  headers: { Authorization: `Bearer ${token}` },
});

from eth_account import Account
from eth_account.messages import encode_defunct
import time, requests

account = Account.from_key("0x...")
timestamp = int(time.time())
message = f"memoclaw-auth:{timestamp}"
signed = account.sign_message(encode_defunct(text=message))

response = requests.post("https://api.memoclaw.com/auth/session", json={
    "address": account.address,
    "timestamp": timestamp,
    "signature": signed.signature.hex(),
})

token = response.json()["token"]

# Use the token for subsequent requests
memories = requests.get("https://api.memoclaw.com/v1/memories",
    headers={"Authorization": f"Bearer {token}"})

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const timestamp = Math.floor(Date.now() / 1000);
const signature = await account.signMessage({
  message: `memoclaw-auth:${timestamp}`,
});

const { token } = await fetch("https://api.memoclaw.com/auth/session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ address: account.address, timestamp, signature }),
}).then(r => r.json());

// Use: Authorization: Bearer {token}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "wallet": "0x1234567890abcdef1234567890abcdef12345678",
  "expires_at": "2026-02-20T17:00:00Z"
}

Errors

Status	Description
401	Invalid signature or expired timestamp.
422	Missing required fields (address, timestamp, signature).

Session tokens are ideal for frontend applications like the dashboard where you don’t want to sign every request. For server-to-server usage, the free tier x-wallet-auth header or x402 payment is more straightforward.