X Twitter Scraper

Integração da API Xquik

Xquik é uma plataforma de dados em tempo real de X (Twitter) fornecendo uma API REST, webhooks HMAC e um servidor MCP para agentes de IA. Cobre monitoramento de conta, extração de dados em massa (19 ferramentas), sorteios de giveaway, lookups de tweet/usuário, verificação de seguimento e tópicos em tendência.

Referência Rápida

Autenticação

Toda solicitação exige uma chave de API via header x-api-key. As chaves começam com xq_ e são geradas no painel Xquik. A chave é exibida apenas uma vez na criação; armazene-a com segurança.

const API_KEY = "xq_YOUR_KEY_HERE";
const BASE = "https://xquik.com/api/v1";
const headers = { "x-api-key": API_KEY, "Content-Type": "application/json" };

Escolhendo o Endpoint Correto

Ferramentas de Extração (19 Tipos)

Fluxo de Extração

// 1. Estimar custo
const estimate = await xquikFetch("/extractions/estimate", {
  method: "POST",
  body: JSON.stringify({ toolType: "follower_explorer", targetUsername: "elonmusk" }),
});

if (!estimate.allowed) return;

// 2. Criar job de extração
const job = await xquikFetch("/extractions", {
  method: "POST",
  body: JSON.stringify({ toolType: "follower_explorer", targetUsername: "elonmusk" }),
});

// 3. Recuperar resultados paginados (até 1.000 por página)
const page = await xquikFetch(`/extractions/${job.id}`);
// page.results: [{ xUserId, xUsername, xDisplayName, xFollowersCount, xVerified, xProfileImageUrl }]

// 4. Exportar como CSV/XLSX/Markdown (limite de 50.000 linhas)
const csvResponse = await fetch(`${BASE}/extractions/${job.id}/export?format=csv`, { headers });

Sorteios de Giveaway

Execute sorteios de giveaway transparentes de respostas a tweets com filtros configuráveis:

const draw = await xquikFetch("/draws", {
  method: "POST",
  body: JSON.stringify({
    tweetUrl: "https://x.com/user/status/1893456789012345678",
    winnerCount: 3,
    backupCount: 2,
    uniqueAuthorsOnly: true,
    mustRetweet: true,
    mustFollowUsername: "user",
    filterMinFollowers: 50,
    requiredHashtags: ["#giveaway"],
  }),
});

const details = await xquikFetch(`/draws/${draw.id}`);
// details.winners: [{ position, authorUsername, tweetId, isBackup }]

Tratamento de Erros e Retry

Todos os erros retornam { "error": "error_code" }. Retry apenas 429 e 5xx (máx. 3 tentativas, backoff exponencial). Nunca retry 4xx exceto 429. Códigos principais:

Configuração do Servidor MCP (Claude Code)

Adicione ao .mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "xquik": {
      "type": "streamable-http",
      "url": "https://xquik.com/mcp",
      "headers": {
        "x-api-key": "xq_YOUR_KEY_HERE"
      }
    }
  }
}

O servidor MCP expõe 22 ferramentas cobrindo todas as capacidades da API. Plataformas suportadas: Claude Code, Claude Desktop, ChatGPT, Codex CLI, Cursor, VS Code, Windsurf, OpenCode.

Padrões de Fluxo

• Alertas em tempo real: add-monitor -> add-webhook -> test-webhook
• Giveaway: get-account (verificar orçamento) -> run-draw
• Extração em massa: estimate-extraction -> run-extraction -> get-extraction
• Análise de tweet: lookup-tweet -> run-extraction com thread_extractor
• Pesquisa de usuário: get-user-info -> search-tweets from:username -> lookup-tweet

Links

• Painel & chaves de API: xquik.com
• Docs completos: docs.xquik.com
• GitHub (fonte da skill): github.com/Xquik-dev/x-twitter-scraper