sentinelx404

Easy-to-use Solana wallet authentication package with advanced verification features. Built with JavaScript for maximum compatibility. Full TypeScript support included!

Installation

npm install sentinelx404
# or
bun add sentinelx404
# or
yarn add sentinelx404

TypeScript Support

This package includes full TypeScript definitions! No need for @ts-ignore or type assertions.

import {
  SentinelAuth,
  detectWallets,
  getGeolocationData,
  X404Blacklist,
  X404TimeLock
} from "sentinelx404";

// Full type safety and IntelliSense support!
const wallets = detectWallets(); // string[]
const location = await getGeolocationData(); // Promise<GeolocationData>
const result = await SentinelAuth({ ... }); // Promise<X404AuthResult>

Quick Start

"use client";

import { useState, useEffect } from "react";
import { detectWallets, getGeolocationData, SentinelAuth } from "sentinelx404";

function App() {
  const [wallets, setWallets] = useState([]);
  const [location, setLocation] = useState({
    latitude: null,
    longitude: null,
    error: null,
    isFetching: false,
  });

  useEffect(() => {
    async function fetchLocation() {
      const locationdata = await getGeolocationData();
      setLocation({
        latitude: locationdata.latitude || null,
        longitude: locationdata.longitude || null,
        error: locationdata.error || null,
        isFetching: false,
      });
    }
    fetchLocation();
  }, []);

  useEffect(() => {
    let wallets = detectWallets();
    setWallets(wallets);
  }, []);

  const RUN = async (wallet) => {
    const config = {
      wallet: wallet,
      required_mint: "TOKEN_CA",
      mint_amount: "TOKEN_AMOUNT",
      geo_code: "true", // or "false"
      geo_code_locs: "US,UK", // Country codes
      coords: {
        latitude: location.latitude,
        longitude: location.longitude,
      },
    };

    const result = await SentinelAuth(config);

    if (result.success) {
      if (result.alreadyAuthenticated) {
        alert("already authenticated");
        console.log(result.token);
        // RUN YOUR CUSTOM LOGIC HERE
      } else {
        console.log(result.token);
        localStorage.setItem("sjwt", result.token); // Token stored automatically
        alert("authenticated");
        // RUN YOUR CUSTOM LOGIC HERE
      }
    } else {
      switch (result.error) {
        case "INSUFFICIENT_TOKENS":
          alert(`You need ${result.required} tokens to access`);
          break;
        case "LOCATION_DENIED":
          alert("Access denied for your location");
          break;
        case "LOCATION_ERROR":
          alert("Location permission denied");
          break;
      }
    }
  };

  return (
    <div>
      {wallets.map((wallet, index) => (
        <button key={index} onClick={() => RUN(wallet)}>
          Connect {wallet}
        </button>
      ))}
    </div>
  );
}

export default App;

Features

This package provides 7 different authentication features:

1. Timelock (default) - Time-based token holding verification
2. Blacklist - Exclusion-based authentication (verify user does NOT hold banned tokens)
3. MultiToken - Multi-token portfolio verification
4. Activity - Transaction history verification
5. Tier - Tiered access levels (Bronze/Silver/Gold)
6. NoDebt - Negative balance verification
7. Age - Wallet age verification

API

detectWallets()

Detect available Solana wallets.

import { detectWallets } from "sentinelx404";

const wallets = detectWallets();
console.log(wallets); // ["phantom", "solflare", "backpack"]

getGeolocationData()

Get user's geolocation data.

import { getGeolocationData } from "sentinelx404";

const location = await getGeolocationData();
console.log(location);
// {
//   latitude: 37.7749,
//   longitude: -122.4194,
//   error: null,
//   isFetching: false
// }

SentinelAuth(config)

Unified authentication function (similar to VelocityAuth).

import { SentinelAuth } from "sentinelx404";

const result = await SentinelAuth({
  wallet: "phantom", // Optional - modal will show if not provided
  required_mint: "TOKEN_CA",
  mint_amount: "1000000",
  feature: "timelock", // Optional, defaults to "timelock"
  geo_code: "false",
  geo_code_locs: "",
  coords: {
    latitude: location.latitude,
    longitude: location.longitude,
  },
});

Individual Feature Functions

You can also use individual feature functions directly:

import { X404TimeLock, X404Blacklist, X404MultiToken } from "sentinelx404";

// Timelock
const result = await X404TimeLock({
  wallet: "phantom", // Optional
  required_mint: "TOKEN_CA",
  mint_amount: "1000000",
  min_hold_duration_days: 30,
  geo_code: "false",
  geo_code_locs: "",
  coords: { latitude: null, longitude: null },
});

// Blacklist
const result = await X404Blacklist({
  excluded_mints: ["scam_token_address"],
  max_holdings: {},
  geo_code: "false",
  geo_code_locs: "",
  coords: { latitude: null, longitude: null },
});

// MultiToken
const result = await X404MultiToken({
  required_tokens: [
    { mint: "TOKEN_A", amount: "10000" },
    { mint: "TOKEN_B", amount: "5000" },
  ],
  verification_mode: "ALL", // or "ANY"
  geo_code: "false",
  geo_code_locs: "",
  coords: { latitude: null, longitude: null },
});

SentinelAuth Configuration

The SentinelAuth function accepts a config object with the following properties:

Common Properties

• wallet (optional) - Wallet name ("phantom", "solflare", "backpack"). If not provided, a modal will appear.
• feature (optional) - Feature to use: "timelock", "blacklist", "multitoken", "activity", "tier", "nodebt", "age". Defaults to "timelock".
• geo_code - Enable geolocation check: "true" or "false"
• geo_code_locs - Allowed country codes (comma-separated): "US,UK"
• coords - Geolocation coordinates object
  • latitude - Latitude (number or null)
  • longitude - Longitude (number or null)

Feature-Specific Properties

Timelock (default)

• required_mint - Token mint address
• mint_amount - Required token amount
• min_hold_duration_days - Minimum hold duration in days

Blacklist

• excluded_mints - Array of excluded token mint addresses
• max_holdings - Object with max holdings per token

MultiToken

• required_tokens - Array of { mint, amount } objects
• verification_mode - "ALL" or "ANY"

Activity

• min_transactions - Minimum number of transactions
• min_volume - Minimum volume (string)
• time_period_days - Time period in days
• transaction_types - Array of transaction types

Tier

• tier_config - Object with bronze, silver, gold tier configs

NoDebt

• check_protocols - Array of protocols to check
• max_debt_allowed - Maximum debt allowed (string)

Age

• min_wallet_age_days - Minimum wallet age in days
• min_first_transaction_days - Minimum first transaction days

Response Format

All authentication functions return a consistent result object:

{
  success: boolean,
  alreadyAuthenticated?: boolean,
  token?: string,
  data?: unknown,
  error?: string,
  message?: string,
  tier?: "bronze" | "silver" | "gold" // For tier feature
}

Error Types

• NONCE_ERROR - Failed to get nonce from server
• SIGNING_ERROR - Failed to sign authentication challenge
• WALLET_CANCELLED - User cancelled wallet selection
• LOCATION_ERROR - Geolocation access error
• LOCATION_DENIED - Access denied for location
• INSUFFICIENT_TOKENS - User doesn't meet token requirements
• INSUFFICIENT_HOLD_DURATION - Tokens not held long enough
• INSUFFICIENT_ACTIVITY - User doesn't meet activity requirements
• HOLDS_BANNED_TOKEN - User holds excluded tokens
• EXCEEDS_MAX_HOLDING - User exceeds max holdings
• HAS_DEBT - User has outstanding debts
• WALLET_TOO_NEW - Wallet doesn't meet age requirements
• UNKNOWN_ERROR - Unexpected error

Token Storage

Each feature automatically stores its JWT token in localStorage:

• sjwt404_timelock - Timelock feature
• sjwt404_blacklist - Blacklist feature
• sjwt404_multitoken - MultiToken feature
• sjwt404_activity - Activity feature
• sjwt404_tier - Tier feature
• sjwt404_nodebt - NoDebt feature
• sjwt404_age - Age feature

Tokens persist across sessions and are automatically checked on subsequent authentication attempts.

Wallet Selection Modal

If you don't provide a wallet in the config, a beautiful modal will automatically appear allowing users to select from their installed wallets.

License

ISC

Author

Manuel Of The North