Blacklist Endpoint

Exclusion-based authentication API endpoint

GET /x404_auth/blacklist

Blacklist Endpoint

cURL

curl --request GET \
  --url https://api.example.com/x404_auth/blacklist \
  --header 'X-404-Addr: <x-404-addr>' \
  --header 'X-404-Feature: <x-404-feature>' \
  --header 'X-404-Nonce: <x-404-nonce>' \
  --header 'X-404-Signature: <x-404-signature>' \
  --header 'excluded_mints: <excluded_mints>' \
  --header 'geo_code: <geo_code>' \
  --header 'geo_code_locs: <geo_code_locs>' \
  --header 'max_holdings: <max_holdings>'

Endpoint

Description

Verifies that a user does NOT hold any tokens from a blacklist of excluded token addresses. This endpoint checks wallet balances and ensures the user doesn’t hold banned tokens or exceed maximum holdings.

Request

Headers

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

X-404-Feature · string · required

Must be "blacklist"

excluded_mints · string · required

JSON array of token mint addresses to exclude (e.g., ["token1", "token2"])

max_holdings · string · required

JSON object mapping mint addresses to maximum allowed holdings (e.g., {"token1": "1000"})

X-Lat · string

User’s latitude (if geolocation enabled)

X-Long · string

User’s longitude (if geolocation enabled)

geo_code · string · required

"true" or "false" to enable/disable geolocation checks

geo_code_locs · string · required

Country code for geolocation filtering (empty string if not used)

x-jwt · string

JWT token from previous authentication (for re-authentication)

Response

Success (200)

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

Error Responses

401 - Location Denied

{
  "status": "locdeny",
  "message": "Access denied for your location"
}

403 - Exceeds Max Holding

{
  "error": "EXCEEDS_MAX_HOLDING",
  "message": "Wallet exceeds maximum holding for token_address. Current: 5000, Max: 1000"
}

500 - Holds Banned Token

{
  "error": "HOLDS_BANNED_TOKEN",
  "message": "Wallet holds excluded token: token_address"
}

500 - Location Error

{
  "status": "locerror",
  "message": "Location access error"
}

Verification Logic

1. Verify signature matches public key
2. Check wallet does NOT hold any tokens in excluded_mints
3. Check wallet does NOT exceed max_holdings for any token
4. Verify geolocation (if enabled)
5. Return JWT token if all checks pass

Example Request

curl -X GET "https://magenx404.onrender.com/x404_auth/blacklist" \
  -H "X-404-Nonce: abc123def456" \
  -H "X-404-Signature: 5KJvsngHeM..." \
  -H "X-404-Addr: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" \
  -H "X-404-Feature: blacklist" \
  -H "excluded_mints: [\"scam_token_1\", \"scam_token_2\"]" \
  -H "max_holdings: {}" \
  -H "geo_code: false" \
  -H "geo_code_locs: "

Example Response

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