API Introduction

Overview of the MagenX404 API

Base URL

All API endpoints are hosted at:

https://magenx404.onrender.com/x404_auth

Authentication Flow

All endpoints follow the same authentication pattern:

1. Request Nonce

   Client makes a GET request to the endpoint. Server returns X-404-Nonce and X-404-Mechanism headers.

2. Sign Challenge

   Client builds payload: CHALLENGE::${nonce}::${path}::${feature} and signs it with the user’s wallet.

3. Send Request

   Client sends GET request with headers: - X-404-Nonce: Nonce from step 1 - X-404-Signature: Base58-encoded signature - X-404-Addr: User’s public key - X-404-Feature: Feature name - Feature-specific headers

4. Receive Token

   Server verifies signature and performs feature-specific checks. Returns JWT token if successful.

Common Headers

All authenticated requests include:

X-404-Nonce · string · required

Nonce received from initial request

X-404-Signature · string · required

Base58-encoded signature of the challenge payload

X-404-Addr · string · required

User’s Solana public key (base58-encoded)

X-404-Feature · string · required

Feature name: "blacklist", "timelock", "multitoken", "activity", "tier", "nodebt", or "age"

x-jwt · string

JWT token from previous authentication (for re-authentication)

Response Format

Success Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "publicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "feature": "blacklist"
}

Error Response

{
  "error": "ERROR_TYPE",
  "message": "Human-readable error message",
  "status": "locerror" // Optional, for location errors
}

Status Codes

200 · number

Success - Authentication successful, JWT token returned

401 · number

Unauthorized - Invalid signature, expired token, or location denied

403 · number

Forbidden - User doesn’t meet requirements (e.g., exceeds max holdings)

500 · number

Server Error - Feature-specific failure or location error

JWT Token Verification

For subsequent requests, clients can send the JWT token in the x-jwt header:

GET /x404_auth/blacklist
x-jwt: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The server will:

1. Verify JWT signature
2. Check expiration
3. Verify token is for the correct feature
4. Return 200 if valid, 401 if invalid

Endpoints

Blacklist

Exclusion-based authentication

TimeLock

Time-based token holding verification

MultiToken

Multi-token portfolio verification

Activity

Transaction history verification

Tier

Tiered access levels

NoDebt

Negative balance verification

Age

Wallet age verification