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>'

import requests

url = "https://api.example.com/x404_auth/blacklist"

headers = {
    "X-404-Nonce": "<x-404-nonce>",
    "X-404-Signature": "<x-404-signature>",
    "X-404-Addr": "<x-404-addr>",
    "X-404-Feature": "<x-404-feature>",
    "excluded_mints": "<excluded_mints>",
    "max_holdings": "<max_holdings>",
    "geo_code": "<geo_code>",
    "geo_code_locs": "<geo_code_locs>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'X-404-Nonce': '<x-404-nonce>',
    'X-404-Signature': '<x-404-signature>',
    'X-404-Addr': '<x-404-addr>',
    'X-404-Feature': '<x-404-feature>',
    excluded_mints: '<excluded_mints>',
    max_holdings: '<max_holdings>',
    geo_code: '<geo_code>',
    geo_code_locs: '<geo_code_locs>'
  }
};

fetch('https://api.example.com/x404_auth/blacklist', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/x404_auth/blacklist",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-404-Addr: <x-404-addr>",
    "X-404-Feature: <x-404-feature>",
    "X-404-Nonce: <x-404-nonce>",
    "X-404-Signature: <x-404-signature>",
    "excluded_mints: <excluded_mints>",
    "geo_code: <geo_code>",
    "geo_code_locs: <geo_code_locs>",
    "max_holdings: <max_holdings>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/x404_auth/blacklist"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-404-Nonce", "<x-404-nonce>")
	req.Header.Add("X-404-Signature", "<x-404-signature>")
	req.Header.Add("X-404-Addr", "<x-404-addr>")
	req.Header.Add("X-404-Feature", "<x-404-feature>")
	req.Header.Add("excluded_mints", "<excluded_mints>")
	req.Header.Add("max_holdings", "<max_holdings>")
	req.Header.Add("geo_code", "<geo_code>")
	req.Header.Add("geo_code_locs", "<geo_code_locs>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/x404_auth/blacklist")
  .header("X-404-Nonce", "<x-404-nonce>")
  .header("X-404-Signature", "<x-404-signature>")
  .header("X-404-Addr", "<x-404-addr>")
  .header("X-404-Feature", "<x-404-feature>")
  .header("excluded_mints", "<excluded_mints>")
  .header("max_holdings", "<max_holdings>")
  .header("geo_code", "<geo_code>")
  .header("geo_code_locs", "<geo_code_locs>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/x404_auth/blacklist")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-404-Nonce"] = '<x-404-nonce>'
request["X-404-Signature"] = '<x-404-signature>'
request["X-404-Addr"] = '<x-404-addr>'
request["X-404-Feature"] = '<x-404-feature>'
request["excluded_mints"] = '<excluded_mints>'
request["max_holdings"] = '<max_holdings>'
request["geo_code"] = '<geo_code>'
request["geo_code_locs"] = '<geo_code_locs>'

response = http.request(request)
puts response.read_body

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"
}