API de recherche par visage pour agents IA (x402)

FaceCheck permet désormais aux agents IA de fouiller Internet par reconnaissance faciale via le protocole x402.

L’agent envoie une photo de visage, règle la recherche en USDC sur Solana et reçoit les pages correspondantes, les miniatures et les scores de confiance — sans compte, sans inscription, sans clé API ni crédits prépayés.

C’est quoi, x402 ?

x402 est un protocole de paiement pour les API.

Il permet à un agent IA de découvrir le prix d’une requête API, de la payer et d’en récupérer le résultat en une simple requête HTTP — en s’appuyant sur le code de statut HTTP 402 Payment Required, réservé depuis longtemps justement pour cet usage.

Côté FaceCheck, cela signifie qu’un agent peut lancer une recherche faciale inversée sur le web ouvert sans compte FaceCheck, sans clé API et sans crédits achetés à l’avance.

Que peuvent en faire les agents ?

Via l’endpoint x402 de FaceCheck, les agents IA peuvent :

• chercher sur Internet des visages correspondants
• repérer les pages où apparaît un visage
• récupérer les URL des correspondances
• obtenir des miniatures en base64
• recevoir des scores de confiance

Endpoint x402

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

Comment ça marche

Tarif

L’endpoint x402 coûte un peu plus par recherche que l’API REST classique, car il inclut la gestion du paiement on-chain et ne demande aucune configuration de compte.

Le prix en vigueur est toujours indiqué dans la réponse 402 Payment Required, avant que l’agent ne paie.

Cette réponse 402 fait foi en matière de tarif.

Exemple de flux HTTP

Le flux HTTP brut tient en trois étapes : découvrir le prix, signer le paiement, envoyer l’image.

1. Découvrir le prix

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

# Réponse :
# HTTP 402 Payment Required
# Indique le prix, la destination du paiement et les détails de la requête

2. Signer le paiement

L’agent signe le paiement avec sa paire de clés Solana. En production, cette étape de signature est généralement prise en charge par une bibliothèque cliente x402.

3. Envoyer l’image

curl -X POST https://facecheck.id/x402/reverse-face-search \
  -H "X-PAYMENT: <paiement signé encodé en base64>" \
  -F "images=@daniel.jpg"

# Réponse :
# Résultats de recherche au format JSON
# Le paiement n’est réglé que si des correspondances sont trouvées

Format de la réponse

Une recherche réussie renvoie un JSON contenant la liste des correspondances :

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

Chaque correspondance contient l’URL d’origine, un score de confiance et une miniature du visage trouvé, encodée en base64.

Avec une bibliothèque cliente

En pratique, on s’appuie sur une bibliothèque cliente x402 qui orchestre tout le flux automatiquement :

1. découvrir le prix
2. signer le paiement
3. relancer la requête avec le paiement attaché
4. récupérer les résultats de la recherche

Exemple avec 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);

Les bibliothèques clientes peuvent varier. Reportez-vous à la documentation de la bibliothèque x402 que vous avez choisie pour les derniers noms de méthodes et la bonne syntaxe.

Frameworks d’agents compatibles

L’endpoint x402 fonctionne avec n’importe quel agent IA ou système de workflow capable de faire des requêtes HTTP et de signer des paiements Solana.

Parmi les options les plus courantes :

• LangChain — workflows d’agents en Python ou JavaScript
• CrewAI — orchestration de tâches multi-agents
• Microsoft AutoGen — conversations et workflows multi-agents
• Claude MCP — appel d’outils via le Model Context Protocol
• Coinbase AgentKit — outillage d’agent pensé pour les paiements crypto
• AutoGPT, Dify et n8n — constructeurs d’agents par workflow

C’est le framework d’agent qui décide quand utiliser l’outil de recherche faciale. Le client x402 s’occupe, lui, de la découverte du prix, de la signature et de la relance de la requête.

x402 vs API REST

FaceCheck.ID propose à la fois l’API REST et le protocole x402.

Quand utiliser x402

Utilisez l’endpoint x402 si vous voulez :

• des agents IA qui font de la recherche faciale inversée sur le web ouvert
• vous passer d’inscription, de clé API ou de crédits prépayés
• payer à l’usage
• des agents autonomes qui paient eux-mêmes leurs outils
• des recherches faciales ponctuelles ou occasionnelles
• la priorité maximale sur les recherches

Utilisez plutôt l’API REST si vous voulez :

• une clé API classique
• des crédits prépayés
• des intégrations applicatives prévisibles
• une utilisation côté serveur
• des intégrations à fort volume ou de longue durée

Foire aux questions

Peut-on tester gratuitement l’endpoint x402 ?

Non. Chaque recherche réussie est payée en USDC sur Solana. Le prix est renvoyé dans la réponse 402 Payment Required avant le paiement : l’agent connaît donc toujours le coût à l’avance.

Que se passe-t-il si aucune correspondance n’est trouvée ?

Vous n’êtes pas facturé. Le paiement on-chain n’est réglé que si la recherche renvoie des résultats.

Faut-il un portefeuille Solana ?

Oui. L’agent doit disposer d’une paire de clés Solana avec de l’USDC pour signer les paiements. Aucun compte FaceCheck n’est nécessaire.

Pourquoi de l’USDC plutôt que de la monnaie fiat ?

L’USDC sur Solana se règle en quelques secondes, avec des frais très bas : c’est ce qui rend réellement viable, en pratique, qu’un agent paie à chaque appel d’API sans intervention humaine.

Peut-on utiliser x402 depuis une appli classique plutôt que depuis un agent IA ?

Oui, mais l’API REST est en général mieux adaptée aux applis et backends traditionnels. x402 est pensé pour un usage autonome, au paiement par appel.

x402 fonctionne-t-il avec Claude, ChatGPT ou d’autres agents LLM ?

Tout framework d’agent capable d’émettre des requêtes HTTP et de signer une transaction Solana peut utiliser l’endpoint — y compris dans des configurations de tool-calling via Claude MCP, LangChain, CrewAI, AutoGen et d’autres. Voir la section « Frameworks d’agents compatibles » ci-dessus.

Pour aller plus loin

• Documentation de l’API REST FaceCheck
• Spécification Swagger
• Conseils pour la recherche faciale inversée par image
• Présentation du protocole x402
• USDC sur Solana

Toutes les recherches FaceCheck sont soumises aux conditions d’utilisation.