Gesichtssuche-API für KI-Agenten (x402)

FaceCheck ermöglicht es KI-Agenten jetzt, das Web per Gesichtssuche zu durchforsten – über das x402-Protokoll.

Ein Agent übergibt ein Gesichtsbild, zahlt die Suche in USDC auf Solana und bekommt passende Webseiten, Thumbnails und Confidence Scores zurück – ganz ohne Konto, Registrierung, API-Key oder Guthaben.

Was ist x402?

x402 ist ein Bezahlprotokoll für APIs.

Damit kann ein KI-Agent den Preis einer API-Anfrage abrufen, sie bezahlen und das Ergebnis in einem ganz normalen HTTP-Request erhalten – auf Basis des seit langem reservierten Statuscodes HTTP 402 Payment Required.

Für FaceCheck heißt das: Ein Agent kann eine Reverse-Gesichtssuche im offenen Web ausführen, ohne dafür ein FaceCheck-Konto, einen API-Key oder vorab gekaufte Credits zu brauchen.

Was können Agenten damit tun?

Über den x402-Endpoint von FaceCheck können KI-Agenten:

• im Web nach passenden Gesichtern suchen
• Webseiten finden, auf denen ein Gesicht erscheint
• die URLs der Treffer abrufen
• Thumbnails als base64 zurückbekommen
• Confidence Scores erhalten

x402-Endpoint

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

Wie es funktioniert

Preise

Eine Suche über den x402-Endpoint kostet etwas mehr als über die klassische REST-API, weil die Onchain-Zahlung mitläuft und überhaupt keine Kontoeinrichtung nötig ist.

Der aktuelle Preis wird immer in der 402 Payment Required-Antwort ausgewiesen, noch bevor der Agent zahlt.

Diese 402-Antwort ist die maßgebliche Quelle für den Preis.

Beispiel für den HTTP-Ablauf

Der reine HTTP-Ablauf besteht aus drei Schritten: Preis abfragen, Zahlung signieren, Bild übermitteln.

1. Preis abfragen

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

# Antwort:
# HTTP 402 Payment Required
# Enthält Preis, Zahlungsempfänger und Details zur Anfrage

2. Zahlung signieren

Der Agent signiert die Zahlung mit seinem Solana-Schlüsselpaar. In der Praxis übernimmt diesen Signiervorgang üblicherweise eine x402-Client-Bibliothek.

3. Bild übermitteln

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

# Antwort:
# Suchergebnisse als JSON
# Die Zahlung wird nur ausgeführt, wenn Treffer gefunden werden

Antwortformat

Eine erfolgreiche Suche liefert ein JSON mit der Trefferliste:

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

Jeder Treffer enthält die Quell-URL, einen Confidence Score und ein base64-codiertes Thumbnail des gefundenen Gesichts.

Mit einer Client-Bibliothek

In der Praxis nutzt man eine x402-Client-Bibliothek, die den kompletten Ablauf automatisch übernimmt:

1. Preis abfragen
2. Zahlung signieren
3. Anfrage mit angehängter Zahlung erneut senden
4. Suchergebnisse empfangen

Beispiel mit 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);

Client-Bibliotheken unterscheiden sich. In der Doku der von dir gewählten x402-Bibliothek findest du die aktuellen Methodennamen und die korrekte Verwendung.

Kompatible Agenten-Frameworks

Der x402-Endpoint funktioniert mit jedem KI-Agenten oder Workflow-System, das HTTP-Anfragen senden und Solana-Zahlungen signieren kann.

Verbreitete Optionen sind unter anderem:

• LangChain – Agenten-Workflows in Python oder JavaScript
• CrewAI – Orchestrierung von Aufgaben mit mehreren Agenten
• Microsoft AutoGen – Multi-Agenten-Konversationen und -Workflows
• Claude MCP – Tool-Calls über das Model Context Protocol
• Coinbase AgentKit – Agenten-Tooling speziell für Krypto-Zahlungen
• AutoGPT, Dify und n8n – Agenten-Baukästen im Workflow-Stil

Wann das Gesichtssuche-Tool aufgerufen wird, entscheidet das Agenten-Framework. Preisermittlung, Signatur und erneutes Senden der Anfrage übernimmt der x402-Client.

x402 vs. REST-API

FaceCheck.ID unterstützt sowohl die REST-API als auch das x402-Protokoll.

Wann x402 sinnvoll ist

Nutze den x402-Endpoint, wenn du Folgendes willst:

• KI-Agenten, die im offenen Web Reverse-Gesichtssuchen ausführen
• keinen Anmeldeprozess, keine API-Keys, keine Credits
• nutzungsbasierte Bezahlung
• autonome Agenten, die ihre Tools selbst bezahlen
• gelegentliche oder einmalige Gesichtsabfragen
• die schnellsten Suchen mit der höchsten Priorität

Nutze die REST-API, wenn du Folgendes willst:

• einen klassischen API-Key
• vorbezahlte Credits
• planbare App-Integrationen
• den Einsatz in Backend-Servern
• größere Mengen oder langlaufende Integrationen

Häufige Fragen

Lässt sich der x402-Endpoint kostenlos ausprobieren?

Nein. Jede erfolgreiche Suche wird in USDC auf Solana bezahlt. Der Preis steht in der 402 Payment Required-Antwort, bevor der Agent zahlt – die Kosten sind also vorher bekannt.

Was passiert, wenn keine Treffer gefunden werden?

Du zahlst nichts. Die Onchain-Zahlung wird nur ausgeführt, wenn die Suche Ergebnisse liefert.

Brauche ich eine Solana-Wallet?

Ja. Der Agent benötigt ein Solana-Schlüsselpaar mit USDC, um Zahlungen zu signieren. Ein FaceCheck-Konto ist nicht erforderlich.

Warum USDC statt Fiat?

USDC auf Solana wird in Sekunden abgewickelt – bei sehr niedrigen Gebühren. Das macht es überhaupt erst praktikabel, dass Agenten pro API-Aufruf bezahlen, ohne dass jemand manuell eingreifen muss.

Lässt sich x402 auch aus einer normalen App nutzen, statt aus einem KI-Agenten?

Ja, aber für klassische Apps und Backends ist meistens die REST-API die bessere Wahl. x402 ist auf autonome Nutzung und Bezahlung pro Aufruf hin optimiert.

Funktioniert x402 mit Claude, ChatGPT oder anderen LLM-Agenten?

Jedes Agenten-Framework, das HTTP-Anfragen senden und eine Solana-Transaktion signieren kann, kann den Endpoint nutzen – inklusive Tool-Calling-Setups über Claude MCP, LangChain, CrewAI, AutoGen und andere. Siehe oben den Abschnitt „Kompatible Agenten-Frameworks“.

Weiterführende Links

• Dokumentation der FaceCheck REST-API
• Swagger-Spezifikation
• Tipps zur Reverse-Bildersuche für Gesichter
• Überblick über das x402-Protokoll
• USDC auf Solana

Für alle FaceCheck-Suchen gelten die Nutzungsbedingungen.