API de Busca Facial para Agentes de IA (x402)

Agora a FaceCheck permite que agentes de IA busquem rostos na internet pelo protocolo x402.

O agente envia uma imagem com o rosto, paga pela busca em USDC na Solana e recebe as páginas encontradas, as miniaturas e as pontuações de confiança — tudo isso sem conta, sem cadastro, sem chave de API e sem créditos pré-pagos.

O que é o x402?

O x402 é um protocolo de pagamento para APIs.

Com ele, um agente de IA consegue descobrir o preço de uma requisição, pagar por ela e receber o resultado em uma única chamada HTTP — usando o código HTTP 402 Payment Required, que ficou reservado por muito tempo justamente para isso.

Na prática, isso quer dizer que o agente pode rodar uma busca facial reversa na web aberta sem precisar criar conta na FaceCheck, gerar chave de API nem comprar créditos antes.

O que dá pra fazer com isso?

Pelo endpoint x402 da FaceCheck, agentes de IA podem:

• procurar rostos correspondentes na internet
• descobrir em quais páginas o rosto aparece
• obter as URLs das correspondências
• receber miniaturas em base64
• obter pontuações de confiança

Endpoint x402

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

Como funciona

Preços

O endpoint x402 sai mais caro por busca do que a API REST tradicional, porque já inclui o processamento do pagamento on-chain e dispensa qualquer configuração de conta.

O preço atual aparece sempre na resposta 402 Payment Required, antes de o agente efetuar o pagamento.

Essa resposta 402 é a fonte oficial do preço.

Exemplo de fluxo HTTP

O fluxo HTTP cru tem três passos: descobrir o preço, assinar o pagamento e enviar a imagem.

1. Descobrir o preço

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

# Resposta:
# HTTP 402 Payment Required
# Traz o preço, o destino do pagamento e os detalhes da requisição

2. Assinar o pagamento

O agente assina o pagamento com o seu par de chaves Solana. Em produção, essa parte costuma ficar a cargo de uma biblioteca cliente x402.

3. Enviar a imagem

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

# Resposta:
# Resultados da busca em JSON
# O pagamento só é liquidado se a busca retornar resultados

Formato da resposta

Uma busca bem-sucedida devolve um JSON com a lista de correspondências:

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

Cada correspondência traz a URL de origem, uma pontuação de confiança e uma miniatura do rosto encontrado, codificada em base64.

Usando uma biblioteca cliente

Na prática, o ideal é usar uma biblioteca cliente x402 que cuide do fluxo inteiro de forma automática:

1. descobrir o preço
2. assinar o pagamento
3. refazer a requisição já com o pagamento anexado
4. receber os resultados da busca

Exemplo usando 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);

As bibliotecas cliente podem variar. Consulte a documentação da biblioteca x402 que você escolher para conferir os nomes de métodos e o uso atualizados.

Frameworks de agentes compatíveis

O endpoint x402 funciona com qualquer agente de IA ou sistema de workflow capaz de fazer requisições HTTP e assinar pagamentos na Solana.

Entre as opções mais comuns:

• LangChain — workflows de agentes em Python ou JavaScript
• CrewAI — orquestração de tarefas com múltiplos agentes
• Microsoft AutoGen — conversas e workflows multiagente
• Claude MCP — chamadas de ferramentas via Model Context Protocol
• Coinbase AgentKit — ferramentas pensadas para agentes com pagamentos em cripto
• AutoGPT, Dify e n8n — construtores de agentes baseados em workflow

Quem decide quando usar a ferramenta de busca facial é o próprio framework do agente. Já o cliente x402 fica com a parte da descoberta do preço, da assinatura e do reenvio da requisição.

x402 vs API REST

A FaceCheck.ID oferece tanto a API REST quanto o protocolo x402.

Quando usar o x402

Use o endpoint x402 quando o objetivo for:

• ter agentes de IA fazendo busca facial reversa na web aberta
• pular qualquer cadastro, chave de API ou compra de créditos
• pagar conforme o uso
• ter agentes autônomos que pagam pelas próprias ferramentas
• fazer consultas faciais avulsas ou esporádicas
• contar com a máxima prioridade nas buscas

Use a API REST quando o objetivo for:

• ter uma chave de API tradicional
• usar créditos pré-pagos
• integrações de aplicativos mais previsíveis
• uso em servidores de backend
• volumes maiores ou integrações de longa duração

Perguntas frequentes

Dá pra testar o endpoint x402 de graça?

Não. Toda busca bem-sucedida é paga em USDC na Solana. O preço já vem na resposta 402 Payment Required, antes do pagamento, então o agente sempre sabe quanto vai gastar antes de seguir adiante.

E se nenhuma correspondência for encontrada?

Você não paga nada. O pagamento on-chain só é liquidado quando a busca retorna resultados.

Preciso de uma carteira Solana?

Sim. O agente precisa de um par de chaves Solana com USDC para assinar os pagamentos. Não é preciso ter conta na FaceCheck.

Por que USDC e não moeda tradicional?

O USDC na Solana é liquidado em segundos, com taxas bem baixas — o que torna viável para agentes pagarem por chamada de API sem precisar de ninguém aprovando cada transação.

Posso usar o x402 a partir de um app comum, em vez de um agente de IA?

Pode, mas para apps e backends tradicionais a API REST costuma encaixar melhor. O x402 foi pensado para uso autônomo, com pagamento por chamada.

O x402 funciona com Claude, ChatGPT ou outros agentes LLM?

Funciona com qualquer framework de agente capaz de fazer requisições HTTP e assinar uma transação na Solana — inclusive em configurações de tool-calling via Claude MCP, LangChain, CrewAI, AutoGen e outros. Veja a seção Frameworks de agentes compatíveis acima.

Para saber mais

• Documentação da API REST da FaceCheck
• Especificação Swagger
• Dicas para busca facial reversa por imagem
• Visão geral do protocolo x402
• USDC na Solana

Todas as buscas da FaceCheck estão sujeitas aos termos de uso.