Authentication

Vision.meme uses wallet-based authentication with JWT (JSON Web Tokens) to secure API endpoints. This ensures that only wallet owners can manage their tokens and settings.

---

Overview

The authentication flow uses a challenge-verify mechanism:

1. Request a challenge message from the API

2. Sign the challenge with your Solana wallet

3. Submit the signature to receive a JWT token

4. Use the JWT token for authenticated requests

Benefits:

• ✅ No passwords needed

• ✅ Cryptographically secure

• ✅ Wallet ownership verified

• ✅ Standard JWT tokens

• ✅ 7-day token lifetime

---

Authentication Flow

Step 1: Request Challenge

Request a unique challenge message for your wallet.

Endpoint: POST /auth/challenge

Request:

json

{
  "walletAddress": "DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK"
}

Response:

json

{
  "challenge": "Sign this message to authenticate: 1234567890",
  "expiresAt": "2024-01-01T12:05:00Z"
}

Details:

• Challenge expires in 5 minutes

• Challenge includes timestamp for uniqueness

• Use the exact challenge message for signing

Step 2: Sign Challenge

Sign the challenge message with your Solana wallet's private key.

Using @solana/web3.js:

javascript

import { sign } from '@noble/ed25519';
import bs58 from 'bs58';

// Convert message to bytes
const messageBytes = new TextEncoder().encode(challenge);

// Sign with private key
const signature = await sign(messageBytes, privateKeyBytes);

// Encode to base58
const signatureBase58 = bs58.encode(signature);

Using Phantom Wallet:

javascript

const message = new TextEncoder().encode(challenge);
const signature = await window.solana.signMessage(message, 'utf8');
const signatureBase58 = bs58.encode(signature);

Using Solflare:

javascript

const message = new TextEncoder().encode(challenge);
const { signature } = await window.solflare.signMessage(message);
const signatureBase58 = bs58.encode(signature);

Step 3: Verify Signature

Submit the signed challenge to receive your JWT token.

Endpoint: POST /auth/verify

Request:

json

{
  "walletAddress": "DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK",
  "signature": "base58_encoded_signature",
  "message": "Sign this message to authenticate: 1234567890"
}

Response:

json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "uuid",
    "walletAddress": "DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK"
  }
}

Details:

• JWT token expires in 7 days

• Token is wallet-specific

• Store token securely for future requests

Step 4: Use Token

Include the JWT token in the Authorization header for authenticated requests.

Header Format:

http

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example Request:

bash

curl https://api.vision.meme/tokens/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

---

Complete Example

JavaScript/TypeScript

javascript

import bs58 from 'bs58';

async function authenticate(walletAddress, signMessage) {
  // Step 1: Request challenge
  const challengeRes = await fetch('https://api.vision.meme/auth/challenge', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ walletAddress })
  });
  
  if (!challengeRes.ok) {
    throw new Error('Failed to get challenge');
  }
  
  const { challenge, expiresAt } = await challengeRes.json();
  console.log('Challenge expires at:', expiresAt);
  
  // Step 2: Sign challenge with wallet
  const messageBytes = new TextEncoder().encode(challenge);
  const signature = await signMessage(messageBytes);
  const signatureBase58 = bs58.encode(signature);
  
  // Step 3: Verify signature and get token
  const verifyRes = await fetch('https://api.vision.meme/auth/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      walletAddress,
      signature: signatureBase58,
      message: challenge
    })
  });
  
  if (!verifyRes.ok) {
    throw new Error('Failed to verify signature');
  }
  
  const { token, user } = await verifyRes.json();
  console.log('Authenticated as:', user.walletAddress);
  
  return token;
}

// Usage with Phantom
async function authenticateWithPhantom() {
  if (!window.solana?.isPhantom) {
    throw new Error('Phantom wallet not found');
  }
  
  await window.solana.connect();
  const walletAddress = window.solana.publicKey.toString();
  
  const signMessage = async (message) => {
    const { signature } = await window.solana.signMessage(message, 'utf8');
    return signature;
  };
  
  return authenticate(walletAddress, signMessage);
}

// Use the token
const token = await authenticateWithPhantom();

// Make authenticated request
const response = await fetch('https://api.vision.meme/tokens/me', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

Python

python

import requests
import base58
from nacl.signing import SigningKey
from nacl.encoding import RawEncoder

def authenticate(wallet_address, private_key_bytes):
    # Step 1: Request challenge
    challenge_res = requests.post(
        'https://api.vision.meme/auth/challenge',
        json={'walletAddress': wallet_address}
    )
    challenge_res.raise_for_status()
    challenge_data = challenge_res.json()
    challenge = challenge_data['challenge']
    
    # Step 2: Sign challenge
    signing_key = SigningKey(private_key_bytes)
    message_bytes = challenge.encode('utf-8')
    signed = signing_key.sign(message_bytes, encoder=RawEncoder)
    signature_base58 = base58.b58encode(signed.signature).decode('utf-8')
    
    # Step 3: Verify signature
    verify_res = requests.post(
        'https://api.vision.meme/auth/verify',
        json={
            'walletAddress': wallet_address,
            'signature': signature_base58,
            'message': challenge
        }
    )
    verify_res.raise_for_status()
    verify_data = verify_res.json()
    
    return verify_data['token']

# Usage
token = authenticate(wallet_address, private_key_bytes)

# Make authenticated request
response = requests.get(
    'https://api.vision.meme/tokens/me',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
)

---

Token Management

Storing Tokens

Client-side (Browser):

javascript

// Store in localStorage
localStorage.setItem('visionmeme_token', token);

// Retrieve
const token = localStorage.getItem('visionmeme_token');

// Remove on logout
localStorage.removeItem('visionmeme_token');

Server-side (Node.js):

javascript

// Store in memory
let authToken = token;

// Or use environment variable
process.env.VISIONMEME_TOKEN = token;

Best Practices:

• ✅ Never expose tokens in client-side code repositories

• ✅ Use environment variables for server-side applications

• ✅ Clear tokens on logout

• ✅ Use secure storage for sensitive applications

• ⚠️ Don't commit tokens to git

Checking Token Expiration

javascript

function isTokenExpired(token) {
  try {
    // Decode JWT payload (without verification)
    const base64Url = token.split('.')[1];
    const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
    const payload = JSON.parse(atob(base64));
    
    // Check expiration (exp is in seconds)
    const expiresAt = payload.exp * 1000;
    const now = Date.now();
    
    return now >= expiresAt;
  } catch (error) {
    return true; // Invalid token
  }
}

// Usage
if (isTokenExpired(token)) {
  console.log('Token expired, need to re-authenticate');
  token = await authenticate();
}

Auto-Refresh Pattern

javascript

class VisionMemeAPI {
  constructor(walletAddress, signMessage) {
    this.walletAddress = walletAddress;
    this.signMessage = signMessage;
    this.token = null;
  }
  
  async getValidToken() {
    if (!this.token || this.isTokenExpired(this.token)) {
      this.token = await this.authenticate();
    }
    return this.token;
  }
  
  isTokenExpired(token) {
    const payload = JSON.parse(atob(token.split('.')[1]));
    return payload.exp * 1000 < Date.now();
  }
  
  async authenticate() {
    // ... authentication logic
  }
  
  async makeRequest(url, options = {}) {
    const token = await this.getValidToken();
    
    return fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });
  }
}

// Usage
const api = new VisionMemeAPI(walletAddress, signMessage);
const response = await api.makeRequest('https://api.vision.meme/tokens/me');

---

Security Best Practices

Never Share Private Keys

javascript

// ❌ NEVER DO THIS
const privateKey = "your_private_key_here";

// ✅ DO THIS
// Use wallet extensions (Phantom, Solflare) for signing
// They handle private keys securely

Validate Wallet Address

javascript

import { PublicKey } from '@solana/web3.js';

function isValidSolanaAddress(address) {
  try {
    new PublicKey(address);
    return true;
  } catch {
    return false;
  }
}

if (!isValidSolanaAddress(walletAddress)) {
  throw new Error('Invalid Solana wallet address');
}

Handle Authentication Errors

javascript

async function safeAuthenticate(walletAddress, signMessage) {
  try {
    return await authenticate(walletAddress, signMessage);
  } catch (error) {
    if (error.message.includes('User rejected')) {
      console.log('User cancelled authentication');
      return null;
    }
    
    if (error.message.includes('expired')) {
      console.log('Challenge expired, please try again');
      return null;
    }
    
    console.error('Authentication failed:', error);
    throw error;
  }
}

Implement Retry Logic

javascript

async function authenticateWithRetry(walletAddress, signMessage, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await authenticate(walletAddress, signMessage);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      console.log(`Authentication attempt ${i + 1} failed, retrying...`);
      await sleep(1000 * (i + 1)); // Exponential backoff
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

---

Common Errors

Challenge Expired

Error:

json

{
  "error": "Challenge expired",
  "message": "The challenge has expired. Please request a new one."
}

Solution:

• Request a new challenge

• Complete signing within 5 minutes

• Don't cache challenges

Invalid Signature

Error:

json

{
  "error": "Invalid signature",
  "message": "The signature could not be verified."
}

Solutions:

• Ensure you're signing the exact challenge message

• Use the correct signing method for your wallet

• Verify wallet address matches the one used for challenge

Invalid Token

Error:

json

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Solutions:

• Check if token has expired (7-day lifetime)

• Re-authenticate to get a new token

• Verify token is correctly formatted in Authorization header

Wallet Not Connected

Error:

javascript

Error: Wallet not connected

Solution:

javascript

if (!window.solana?.isConnected) {
  await window.solana.connect();
}

---

Rate Limits

Authentication endpoints have specific rate limits:

Endpoint	Limit
POST /auth/challenge	20 requests per minute
POST /auth/verify	20 requests per minute

Exceeded Rate Limit:

json

{
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

Wait for the retryAfter seconds before trying again.

---

Testing Authentication

Test on Devnet

javascript

// Use devnet wallet for testing
const devnetWallet = Keypair.generate();
const walletAddress = devnetWallet.publicKey.toString();

// Test authentication flow
const token = await authenticate(
  walletAddress,
  async (message) => {
    const signature = await sign(message, devnetWallet.secretKey.slice(0, 32));
    return signature;
  }
);

console.log('Test authentication successful:', !!token);

Verify Token Payload

javascript

function decodeToken(token) {
  const parts = token.split('.');
  const payload = JSON.parse(atob(parts[1]));
  
  console.log('Token payload:', {
    userId: payload.sub,
    walletAddress: payload.wallet,
    issuedAt: new Date(payload.iat * 1000),
    expiresAt: new Date(payload.exp * 1000)
  });
  
  return payload;
}

---

Next Steps

• Rate Limits - Understand API rate limiting

• Token Endpoints - Start creating tokens

• Code Examples - More integration examples

---

Need Help?

• 💬 Discord Community

• 📱 Telegram Support

• 📧 Email Support

---

© 2025 Vision.meme. All rights reserved.