Wallet Authentication

KnowledgeFlowDB uses a 3-layer wallet-based authentication system. Your Ethereum wallet address is your identity — no accounts, passwords, or API keys needed.

Overview

Layer	Purpose	When to Use
Layer 1	EIP-191 challenge/verify → Bearer JWT (24h)	Production apps needing authenticated sessions
Layer 2	x402 EIP-712 payment authorization	MCP tool calls requiring payment
Layer 3	Combined Bearer + x402	Full production flow (identity + payment)

Layer 1: Challenge/Verify Authentication

This is the primary authentication method. It proves wallet ownership via EIP-191 signature and returns a JWT valid for 24 hours.

Step 1: Get a Challenge

curl https://api.knowledgedataflow.org/api/auth/challenge

Response:

{
  "nonce": "abc123...",
  "message": "Sign this message to authenticate with KnowledgeFlowDB.\n\nNonce: abc123..."
}

Step 2: Sign the Message

Sign the message field with your wallet using EIP-191 personal_sign. This proves you control the wallet without revealing your private key.

Step 3: Verify and Get Token

curl -X POST https://api.knowledgedataflow.org/api/auth/verify \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0xYOUR_WALLET_ADDRESS",
    "signature": "0xSIGNATURE_FROM_STEP_2",
    "nonce": "abc123..."
  }'

Response:

{
  "token": "eyJhbGciOi...",
  "walletAddress": "0xYOUR_WALLET_ADDRESS",
  "expiresAt": "2026-03-25T12:00:00Z"
}

Step 4: Use the Token

Include the JWT in subsequent requests:

curl -X POST https://api.knowledgedataflow.org/api/v1/query \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (n) RETURN count(n)"}'

Layer 2: x402 Payment Protocol

For MCP tool calls, payment is authorized via the x402 protocol using EIP-712 TransferWithAuthorization:

• Token: USDC on Base chain (chain ID 8453)
• Cost: $0.0005 per tool call
• Header: X-PAYMENT containing the signed authorization

The payment is gasless for the user — the facilitator submits the transaction. See x402 Payments for details.

Layer 3: Combined Flow

In production, Bearer and x402 work together:

1. Bearer token identifies the wallet and loads user secrets (e.g., stored API keys for MCP servers)
2. X-PAYMENT header authorizes the USDC transfer for the tool call

Request Headers:
  Authorization: Bearer eyJhbGciOi...    ← identifies wallet, loads secrets
  X-PAYMENT: <signed-x402-authorization>  ← authorizes payment

Simple Access: X-Wallet-Address

For development and testing, you can skip the challenge/verify flow and pass your wallet address directly:

curl -X POST https://api.knowledgedataflow.org/api/v1/query \
  -H "X-Wallet-Address: 0xYOUR_WALLET_ADDRESS" \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (n) RETURN count(n)"}'

This is convenient for local development but does not cryptographically prove wallet ownership.

Free Endpoints

These endpoints require no authentication or payment:

Endpoint	Method	Description
/health	GET	Health check
/api/servers	GET	List MCP servers
/api/servers/:id/tools	GET	List server tools
/api/servers/:id/skill	GET	Get server skill documentation

SDK Integration

The rickydata SDK handles the full authentication flow automatically:

import { AuthManager } from '@nickydata/sdk';

const auth = new AuthManager('https://api.knowledgedataflow.org');
await auth.authenticateAuto({
  signFn: wallet.signMessage,
  walletAddress: wallet.address,
});