STATUS: ONLINE

LAST_UPDATED: 2025-12-14

TECHNICAL SPECIFICATION

Comprehensive documentation for the XED Screener infrastructure. This registry serves as the immutable source of truth for SPL token metadata mapping, providing high-availability access to asset information via decentralized storage endpoints.

01 // System Architecture

INFRA_V2


+----------------+       +-------------------+       +---------------------+
|  CLIENT LAYER  | ----> |  EDGE MIDDLEWARE  | ----> |  PERSISTENCE LAYER  |
+----------------+       +-------------------+       +---------------------+
|                |       |                   |       |                     |
|  React / UI    |       |  Next.js API      |       |  Supabase DB (PG)   |
|  (Start Page)  |       |  (Rate Limiting)  |       |  (Token Records)    |
|                |       |  (Validation)     |       |                     |
+-------+--------+       +---------+---------+       +----------+----------+
        |                          |                            |
        | Direct Upload            | Auth / Write               | Read / Query
        v                          v                            v
+-------+--------+       +---------+---------+       +----------+----------+
| OBJECT STORAGE |       |  SECURITY MODULE  |       |  PUBLIC ENDPOINTS   |
+----------------+       +-------------------+       +---------------------+
|                |       |                   |       |                     |
| Supabase Buckets|      |  Cooldown Logic   |       |  GET /api/token     |
| (Images/Assets)|       |  Admin Gate       |       |  (CDN Cached)       |
|                |       |                   |       |                     |
+----------------+       +-------------------+       +---------------------+

EXECUTION ENVIRONMENT

Runtime Node.js / Edge
Region Global / Distributed
Latency <50ms (p99)
Consistency Strong (Write) / Eventual (Read)

DEPENDENCIES

@supabase/js v2.86.2
next v16.0.7
react v19.2.0
tailwindcss v4.1.18
@vercel/analytics v1.6.1

02 // Security & Validation

SEC_LEVEL_HIGH

Input Sanitization

All incoming payloads undergo strict type checking and sanitization. Base58 addresses are regex-validated before processing to prevent injection attacks.

Rate Limiting

All API endpoints are protected with sliding window rate limiting per IP address.

SUBMIT: 5 REQ / MIN
GENERAL: 30-100 REQ / MIN

Submissions also have cooldown: 1 REQ / 3 HRS per wallet+mint

Asset Verification

Image assets are isolated in a public storage bucket with strict CORS policies. Max file size constraints (5MB) are enforced at the upload edge.

Authentication

Optional Google OAuth via Supabase Auth. Sign-in enables future features like cross-device watchlist sync. All core features remain accessible without authentication.

Error Boundaries

React error boundaries catch and gracefully handle component failures, preventing full page crashes and providing user-friendly error messages.

03 // API Endpoints

REST_V1

POST/api/submit

Primary ingestion endpoint for metadata registration. Handles cooldown checks, validation, and database persistence. Rate limited to 5 requests per minute per IP.

Request Body

{
  "wallet": "So111...111",  // required, base58
  "mint": "EPjFW...e76",    // required, base58
  "name": "USD Coin",       // required, max 80
  "symbol": "USDC",         // required, max 16
  "description": "Stable...", // required, max 1000
  "image": "https://...",   // required, url, max 500
  "twitter": "https://...", // optional, max 200
  "telegram": "https://...", // optional, max 200
  "website": "https://..."  // optional, max 500
}

Success Response (200)

{
  "success": true,
  "id": "550e8400-e29b...",
  "timestamp": 1715421234,
  "status": "pending"
}

GET/api/token

Public resolution endpoint. Returns the latest approved metadata for a given mint address. Used by wallets and explorers.

Query Parameters

PARAM

TYPE

DESCRIPTION

mint

string

The Solana mint address to resolve.

GET/api/explorer

Paginated listing of all approved tokens. Supports search and sorting.

Query Parameters

PARAM

TYPE

DESCRIPTION

page

number

Page number (default: 1)

limit

number

Items per page (max: 50, default: 20)

string

Search by name, symbol, or mint

sort

string

Sort by: newest, oldest, name

GET/api/dexscreener

Fetches live market data from DexScreener API. Returns price, volume, liquidity, market cap, and trading data. Cached for 60 seconds.

Query Parameters

PARAM

TYPE

DESCRIPTION

mint

string

Token mint address

GET/api/search

Autocomplete search endpoint. Returns up to 8 matching tokens by name, symbol, or mint address.

Query Parameters

PARAM

TYPE

DESCRIPTION

string

Search query (min 2 characters)

GET/api/stats

Returns aggregate statistics: total tokens, pending, approved, and rejected counts. Cached for 1 minute.

GET/api/activity

Returns the 10 most recently approved tokens for activity feed display.

04 // Data Models

PG_SCHEMA

Column Name	Data Type	Constraint	Description
id	uuid	PK, DEFAULT gen_random_uuid()	Unique record identifier
created_at	timestamptz	DEFAULT now()	Submission timestamp (used for cooldowns)
wallet	varchar(44)	NOT NULL	Submitter's public key
mint	varchar(44)	NOT NULL	Target token mint address
metadata_blob	jsonb		Flexible storage for name, symbol, description
status	enum	DEFAULT 'pending'	Lifecycle state (pending → approved/rejected)

XED_SCREENER_SYSTEM // END_OF_FILE

CONFIDENTIALITY_LEVEL: PUBLIC