API di ricerca facciale per agenti AI (x402)

Da oggi FaceCheck permette agli agenti AI di cercare un volto su Internet tramite il protocollo x402.

Un agente invia l’immagine di un volto, paga la ricerca in USDC su Solana e riceve le pagine web corrispondenti, le miniature e i punteggi di confidenza — senza bisogno di account, registrazione, chiave API o crediti prepagati.

Cos’è x402?

x402 è un protocollo di pagamento pensato per le API.

Permette a un agente AI di scoprire il prezzo di una richiesta, pagarla e ricevere il risultato con una normale richiesta HTTP — sfruttando il codice di stato HTTP 402 Payment Required, riservato da tempo proprio per questo scopo.

In concreto, per FaceCheck questo significa che un agente può fare una ricerca facciale inversa sul web aperto senza aprire un account FaceCheck, generare una chiave API o comprare crediti in anticipo.

Cosa possono farci gli agenti?

Tramite l’endpoint x402 di FaceCheck, gli agenti AI possono:

• cercare nel web volti corrispondenti
• individuare le pagine in cui compare un volto
• recuperare gli URL dei risultati
• ottenere miniature in base64
• ricevere punteggi di confidenza

Endpoint x402

https://facecheck.id/x402/reverse-face-search

Come funziona

Prezzi

L’endpoint x402 costa un po’ di più per ricerca rispetto all’API REST classica, perché include la gestione del pagamento on-chain e non richiede nessuna configurazione dell’account.

Il prezzo aggiornato viene sempre indicato nella risposta 402 Payment Required prima che l’agente paghi.

È proprio questa risposta 402 a fare fede sul prezzo.

Esempio di flusso HTTP

Il flusso HTTP grezzo si compone di tre passaggi: scoprire il prezzo, firmare il pagamento e inviare l’immagine.

1. Scoprire il prezzo

curl https://facecheck.id/x402/reverse-face-search

# Risposta:
# HTTP 402 Payment Required
# Include prezzo, destinazione del pagamento e dettagli della richiesta

2. Firmare il pagamento

L’agente firma il pagamento con la propria coppia di chiavi Solana. In produzione, questo passaggio è di solito gestito da una libreria client x402.

3. Inviare l’immagine

curl -X POST https://facecheck.id/x402/reverse-face-search \
  -H "X-PAYMENT: <pagamento firmato in base64>" \
  -F "images=@daniel.jpg"

# Risposta:
# Risultati della ricerca in JSON
# Il pagamento viene effettivamente regolato solo se ci sono risultati

Formato della risposta

Una ricerca andata a buon fine restituisce un JSON con l’elenco delle corrispondenze:

{
  "match_count": 3,
  "took_ms": 4127,
  "matches": [
    {
      "url": "https://example.com/page-where-face-appears",
      "score": 92,
      "thumb_base64": "iVBORw0KGgoAAAANS..."
    }
  ]
}

Ogni corrispondenza contiene l’URL di origine, un punteggio di confidenza e una miniatura in base64 del volto trovato.

Usare una libreria client

Nella pratica conviene affidarsi a una libreria client x402 che gestisca l’intero flusso in automatico:

1. scopre il prezzo
2. firma il pagamento
3. rinvia la richiesta con il pagamento allegato
4. riceve i risultati della ricerca

Esempio con x402-solana:

"""
Search the internet by face via FaceCheck's x402 endpoint.
Pays per call in USDC on Solana — no account, no API key.

Setup:
    pip install requests "x402[svm]"
    export SOLANA_KEYPAIR=<your base58 Solana secret key>
"""

import base64
import os
import requests
from x402 import x402ClientSync, parse_payment_required
from x402.mechanisms.svm import KeypairSigner
from x402.mechanisms.svm.exact.register import register_exact_svm_client

URL = "https://facecheck.id/x402/reverse-face-search"
IMAGE = "face.jpg"

# Set up the x402 client with your Solana wallet
client = x402ClientSync()
signer = KeypairSigner.from_base58(os.environ["SOLANA_KEYPAIR"])
register_exact_svm_client(client, signer)

# Step 1: GET the endpoint to discover price and payment destination.
payment_required = parse_payment_required(requests.get(URL).json())

# Step 2: Sign a USDC transfer authorization with your Solana keypair.
payload = client.create_payment_payload(payment_required)
payment_header = base64.b64encode(
    payload.model_dump_json(by_alias=True).encode()
).decode()

# Step 3: POST the image with the signed payment attached. The server
# verifies, runs the search, and only settles on-chain if results are found.
image = open(IMAGE, "rb").read()
r = requests.post(URL, data=image, headers={
    "Content-Type": "image/jpeg",
    "PAYMENT-SIGNATURE": payment_header,
})
result = r.json()

# Step 4: Iterate the matches (each has a base64-encoded thumbnail)
print(f"found {result['match_count']} matches in {result['took_ms']}ms")
for m in result["matches"]:
    thumb = m["thumb_base64"][:30]
    print(f"  score={m['score']}  thumb={thumb}...  {m['url']}")

/**
 * Search the internet by face via FaceCheck's x402 endpoint.
 * Pays per call in USDC on Solana — no account, no API key.
 *
 * Setup:
 *   npm install x402-solana @solana/web3.js bs58
 *   export SOLANA_KEYPAIR=<your base58 Solana secret key>
 *
 * Run:
 *   npx tsx test_client_minimal.ts
 */

import { createX402Client } from 'x402-solana/client';
import { Keypair, Transaction, VersionedTransaction } from '@solana/web3.js';
import bs58 from 'bs58';
import { readFileSync } from 'fs';

const URL = 'https://facecheck.id/x402/reverse-face-search';
const IMAGE = 'face.jpg';

async function main() {
  // Wrap a Node-side keypair in the WalletAdapter shape x402-solana expects
  const keypair = Keypair.fromSecretKey(bs58.decode(process.env.SOLANA_KEYPAIR!));
  const wallet = {
    publicKey: keypair.publicKey,
    signTransaction: async <T extends Transaction | VersionedTransaction>(tx: T): Promise<T> => {
      if (tx instanceof VersionedTransaction) tx.sign([keypair]);
      else tx.partialSign(keypair);
      return tx;
    },
  };

  // x402 client auto-handles the 402 → sign → retry flow
  const client = createX402Client({
    wallet,
    network: 'solana',                    // mainnet
    maxPaymentAmount: BigInt(5_000_000),  // safety cap: max $5.00 USDC per call
  });

  // POST the image; client handles payment transparently
  const response = await client.fetch(URL, {
    method: 'POST',
    headers: { 'Content-Type': 'image/jpeg' },
    body: readFileSync(IMAGE),
  });

  const result = await response.json();

  console.log(`found ${result.match_count} matches in ${result.took_ms}ms`);
  for (const m of result.matches) {
    console.log(`  score=${m.score}  thumb=${m.thumb_base64.slice(0, 30)}...  ${m.url}`);
  }
}

main().catch(console.error);

Le librerie client possono variare. Per i nomi dei metodi e l’uso aggiornati, consulta sempre la documentazione della libreria x402 che hai scelto.

Framework di agenti compatibili

L’endpoint x402 funziona con qualunque agente AI o sistema di workflow in grado di fare richieste HTTP e firmare pagamenti su Solana.

Le opzioni più diffuse includono:

• LangChain — workflow di agenti in Python o JavaScript
• CrewAI — orchestrazione di task multi-agente
• Microsoft AutoGen — conversazioni e workflow multi-agente
• Claude MCP — invocazione di tool tramite Model Context Protocol
• Coinbase AgentKit — strumenti per agenti pensati per i pagamenti crypto
• AutoGPT, Dify e n8n — costruttori di agenti in stile workflow

A decidere quando usare lo strumento di ricerca facciale è il framework dell’agente. Il client x402, invece, si occupa di scoprire il prezzo, firmare e rilanciare la richiesta.

x402 vs API REST

FaceCheck.ID supporta sia l’API REST sia il protocollo x402.

Quando usare x402

Usa l’endpoint x402 se vuoi:

• agenti AI che fanno ricerca facciale inversa sul web aperto
• evitare registrazione, chiavi API e crediti prepagati
• pagare a consumo
• agenti autonomi che pagano direttamente per i propri strumenti
• ricerche facciali sporadiche o occasionali
• la massima priorità sulle ricerche

Usa l’API REST se vuoi:

• una chiave API tradizionale
• crediti prepagati
• integrazioni applicative prevedibili
• uso da server di backend
• volumi elevati o integrazioni di lunga durata

Domande frequenti

L’endpoint x402 si può provare gratis?

No. Ogni ricerca andata a buon fine viene pagata in USDC su Solana. Il prezzo arriva già nella risposta 402 Payment Required, prima del pagamento, così l’agente conosce sempre il costo in anticipo.

Cosa succede se non ci sono risultati?

Non paghi nulla. Il pagamento on-chain viene effettivamente regolato solo se la ricerca restituisce dei risultati.

Mi serve un wallet Solana?

Sì. L’agente ha bisogno di una coppia di chiavi Solana con USDC per firmare i pagamenti. Non serve invece nessun account FaceCheck.

Perché USDC e non valuta tradizionale?

USDC su Solana viene regolato in pochi secondi e con commissioni bassissime: è questo a rendere davvero praticabile l’idea che un agente paghi per ogni singola chiamata API, senza alcun intervento umano.

Posso usare x402 da una normale app, invece che da un agente AI?

Puoi, ma per app e backend tradizionali di solito l’API REST è la scelta più adatta. x402 è ottimizzato per un uso autonomo e per il pagamento a chiamata.

x402 funziona con Claude, ChatGPT o altri agenti LLM?

Qualunque framework di agenti capace di fare richieste HTTP e firmare una transazione Solana può usare l’endpoint — incluse le configurazioni di tool-calling con Claude MCP, LangChain, CrewAI, AutoGen e altri. Vedi la sezione “Framework di agenti compatibili” qui sopra.

Approfondimenti

• Documentazione dell’API REST di FaceCheck
• Specifica Swagger
• Consigli per la ricerca facciale inversa da immagine
• Panoramica del protocollo x402
• USDC su Solana

Tutte le ricerche di FaceCheck sono soggette ai termini di utilizzo.