API de búsqueda por rostro para agentes de IA (x402)

FaceCheck ya permite que los agentes de IA busquen caras en Internet a través del protocolo x402.

El agente envía una imagen de la cara, paga la búsqueda en USDC sobre Solana y recibe a cambio las páginas que coinciden, las miniaturas y las puntuaciones de confianza — sin cuenta, sin registro, sin clave de API y sin créditos prepago.

¿Qué es x402?

x402 es un protocolo de pago pensado para APIs.

Permite que un agente de IA consulte el precio de una petición, la pague y reciba el resultado en una petición HTTP normal — apoyándose en el código de estado HTTP 402 Payment Required, que llevaba años reservado precisamente para esto.

En el caso de FaceCheck, eso significa que un agente puede hacer una búsqueda facial inversa en la web abierta sin necesidad de cuenta de FaceCheck, ni de clave de API, ni de créditos comprados por adelantado.

¿Qué pueden hacer los agentes con esto?

A través del endpoint x402 de FaceCheck, los agentes de IA pueden:

• buscar caras coincidentes en Internet
• localizar páginas donde aparece un rostro
• obtener las URL de las coincidencias
• recibir miniaturas en base64
• conseguir puntuaciones de confianza

Endpoint x402

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

Cómo funciona

Precios

El endpoint x402 cuesta algo más por búsqueda que la API REST normal, porque incluye toda la gestión de pago on-chain y no requiere absolutamente ninguna configuración de cuenta.

El precio actual siempre aparece en la respuesta 402 Payment Required antes de que el agente pague.

Esa respuesta 402 es la fuente oficial del precio.

Ejemplo de flujo HTTP

El flujo HTTP puro consta de tres pasos: consultar el precio, firmar el pago y enviar la imagen.

1. Consultar el precio

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

# Respuesta:
# HTTP 402 Payment Required
# Incluye el precio, el destino del pago y los detalles de la petición

2. Firmar el pago

El agente firma el pago con su par de claves Solana. En producción, lo habitual es que de este paso se encargue una librería cliente de x402.

3. Enviar la imagen

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

# Respuesta:
# Resultados de la búsqueda en JSON
# El pago solo se liquida si la búsqueda devuelve resultados

Formato de respuesta

Una búsqueda con éxito devuelve un JSON con la lista de coincidencias:

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

Cada coincidencia incluye la URL de origen, una puntuación de confianza y una miniatura en base64 del rostro encontrado.

Con una librería cliente

En la práctica, lo más cómodo es usar una librería cliente de x402 que gestione todo el flujo de forma automática:

1. consulta el precio
2. firma el pago
3. reenvía la petición con el pago adjunto
4. recibe los resultados de la búsqueda

Ejemplo 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);

Las librerías cliente pueden variar. Consulta la documentación de la librería x402 que hayas elegido para ver los nombres de métodos y el uso más actualizado.

Frameworks de agentes compatibles

El endpoint x402 funciona con cualquier agente de IA o sistema de workflows que pueda hacer peticiones HTTP y firmar pagos en Solana.

Algunas opciones habituales:

• LangChain — flujos de agentes en Python o JavaScript
• CrewAI — orquestación de tareas con varios agentes
• Microsoft AutoGen — conversaciones y flujos multiagente
• Claude MCP — llamada a herramientas mediante Model Context Protocol
• Coinbase AgentKit — herramientas para agentes pensadas para pagos en cripto
• AutoGPT, Dify y n8n — constructores de agentes en formato workflow

Es el framework del agente el que decide cuándo usar la herramienta de búsqueda facial. El cliente x402, por su parte, se encarga de consultar el precio, firmar y reintentar la petición.

x402 vs API REST

FaceCheck.ID soporta tanto la API REST como el protocolo x402.

Cuándo conviene usar x402

Usa el endpoint x402 cuando quieras:

• que agentes de IA hagan búsquedas faciales inversas en la web abierta
• evitar registros, claves de API y créditos prepago
• pagar por uso
• agentes autónomos capaces de pagar sus propias herramientas
• consultas faciales puntuales o esporádicas
• la máxima prioridad en las búsquedas

Usa la API REST cuando quieras:

• una clave de API tradicional
• créditos prepago
• integraciones de aplicación predecibles
• uso desde servidores backend
• volúmenes altos o integraciones de larga duración

Preguntas frecuentes

¿Puedo probar el endpoint x402 gratis?

No. Cada búsqueda con resultados se paga en USDC sobre Solana. El precio llega en la respuesta 402 Payment Required antes del pago, así que el agente conoce el coste de antemano.

¿Y si no encuentra ninguna coincidencia?

No se cobra. El pago on-chain solo se liquida si la búsqueda devuelve resultados.

¿Necesito un wallet de Solana?

Sí. El agente necesita un par de claves Solana con USDC para firmar los pagos. No hace falta tener cuenta de FaceCheck.

¿Por qué USDC y no dinero fiat?

El USDC sobre Solana se liquida en segundos y con comisiones muy bajas, así que resulta práctico que un agente pague por cada llamada a la API sin que tenga que intervenir nadie.

¿Puedo usar x402 desde una aplicación normal en vez de un agente de IA?

Sí, pero para apps y backends tradicionales suele encajar mejor la API REST. x402 está pensado para uso autónomo, con pago por llamada.

¿Funciona x402 con Claude, ChatGPT u otros agentes LLM?

Cualquier framework de agente que pueda hacer peticiones HTTP y firmar una transacción de Solana puede usar el endpoint, incluidas las configuraciones de tool-calling con Claude MCP, LangChain, CrewAI, AutoGen y otros. Mira el apartado «Frameworks de agentes compatibles» más arriba.

Lecturas relacionadas

• Documentación de la API REST de FaceCheck
• Especificación Swagger
• Consejos para la búsqueda facial inversa por imagen
• Resumen del protocolo x402
• USDC sobre Solana

Todas las búsquedas de FaceCheck están sujetas a las condiciones de uso.