Crie um bot do Telegram para Solana em menos de 100 linhas de código

Como configurar seu projeto

Vamos colocar seu projeto em funcionamento:

1. Clone o repositório

git clone https://github.com/helius-labs/cloudfare-telegram-template.git

cd cloudfare-telegram-template

2. Instale as dependências

npm install

3. Configure as variáveis de ambiente

Abra wrangler.toml e preencha as seguintes chaves:

TELEGRAM_BOT_TOKEN

1. Abra o Telegram e procure por @BotFather.
2. Inicie uma conversa com o BotFather e envie o comando /newbot. 
3. Siga as instruções para escolher um nome e um nome de usuário para seu bot. 
4. Após a criação, o BotFather fornecerá um token. Esse é seu TELEGRAM_BOT_TOKEN. 

TELEGRAM_CHAT_ID

1. Crie um canal e adicione seu bot como administrador.
2. Envie uma mensagem ao canal.
3. Acesse: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
4. Encontre o campo "chat":{"id": na resposta. Esse é seu TELEGRAM_CHAT_ID.
5. Assista a este vídeo para conferir um guia passo a passo:

HELIUS_API_KEY Sua chave de API da Helius (obtenha-a na Helius)

AUTH_TOKEN Abra o bash e gere um AUTH_TOKEN exclusivo:

openssl rand -base64 32

4. Faça o deploy no Cloudflare

npm run deploy

Depois de executar esse comando, você verá a URL do deploy na saída do console. Anote essa URL, pois você precisará dela na próxima etapa.

5. Crie seu webhook

Use a URL do deploy da etapa anterior para criar seu webhook:

curl -X POST https://your-worker-url.workers.dev/create-webhook

Você receberá uma resposta de sucesso depois de executar esse comando.

Você pode ver o novo webhook configurado no painel da Helius.

6. Edite seu webhook

Depois de criar seu webhook, você poderá personalizá-lo ainda mais no painel da Helius: 

1. Acesse a seção de webhooks no painel
2. Seu webhook recém-criado deverá aparecer na lista. 
3. Clique no webhook para editar suas configurações.
4. Nessa página, você pode modificar diversos parâmetros, como:
   • Tipos de transação que deseja acompanhar
   • Endereços específicos de carteiras que deseja monitorar
   • Rede (mainnet, devnet)

Detalhamento do código

Primeiro, vamos analisar nossas importações e definições de tipos:

import { Hono } from 'hono';

type Env = {
  HELIUS_API_KEY: string;
  TELEGRAM_BOT_TOKEN: string;
  TELEGRAM_CHAT_ID: string;
  AUTH_TOKEN: string;
};

‍Estamos usando o Hono, um framework web leve para Cloudflare Workers. O tipo Env define nossas variáveis de ambiente para as integrações com a Helius e o Telegram.

Em seguida, configuramos nosso aplicativo Hono:‍

const app = new Hono<{ Bindings: Env }>();

app.get('/', (c) => c.text('Solana Action Bot is running!'));

Isso cria nosso aplicativo e configura um endpoint simples para verificar sua integridade.

Agora, vamos criar nosso webhook:

app.post('/create-webhook', async (c) => {
  const webhookURL = `${new URL(c.req.url).origin}/webhook`;
  console.log('Setting up webhook with URL:', webhookURL);

  const response = await fetch(
    `https://api.helius.xyz/v0/webhooks?api-key=${c.env.HELIUS_API_KEY}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        webhookURL: webhookURL,
        transactionTypes: ["NFT_SALE"],
        accountAddresses: ["M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K"], // Magic Eden v2 program
        webhookType: "enhanced",
        authHeader: c.env.AUTH_TOKEN
      }),
    }
  );
  const data = await response.json();
  console.log('Helius webhook setup response:', data);
  return c.json({ success: true, webhook: data, webhookURL: webhookURL });
});

Esse endpoint configura nosso webhook da Helius. Neste exemplo, estamos acompanhando vendas de NFT do programa Magic Eden v2, mas você pode modificar transactionTypes e accountAddresses conforme suas necessidades.‍

Veja como enviamos mensagens ao Telegram:

async function sendTelegramMessage(message: string, env: Env) {
  const url = `https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/sendMessage`;
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      chat_id: env.TELEGRAM_CHAT_ID,
      text: message,
      parse_mode: 'Markdown',
    }),
  });
  return response.json();
}

Essa função formata nossa mensagem e a envia ao nosso chat do Telegram.

Por fim, vamos processar os dados recebidos pelo webhook:

app.post('/webhook', async (c) => {

  const authToken = c.req.header('Authorization');
  if (authToken !== c.env.AUTH_TOKEN) {
    return c.text('Unauthorized', 401);
  }

  let data;
  try {
    data = await c.req.json();
    console.log('Received webhook data:', JSON.stringify(data, null, 2));
  } catch (error) {
    console.error('Error parsing webhook data:', error);
    return c.text('Error processing webhook', 400);
  }

  if (!Array.isArray(data) || data.length === 0) {
    console.log('No transactions in webhook data');
    return c.text('No transactions to process', 200);
  }

  for (const transaction of data) {
    if (transaction.type === 'NFT_SALE') {
      const { amount, buyer, seller, signature, nfts } = transaction.events.nft;
      const message = `🎉 *NFT Sale*\n\n` +
        `*Price*: ${amount / 1e9} SOL\n` +
        `*Buyer*: \`${buyer}\`\n` +
        `*Seller*: \`${seller}\`\n` +
        `*Signature*: [View on Solana Explorer](https://explorer.solana.com/tx/${signature})`;

      try {
        const result = await sendTelegramMessage(message, c.env);
        console.log('Telegram message sent:', result);
      } catch (error) {
        console.error('Error sending Telegram message:', error);
      }
    }
  }

  return c.text('Webhook processed');
});

‍É aqui que processamos os dados da Helius e enviamos mensagens formatadas ao Telegram. Conforme seu caso de uso, você pode personalizar essa parte para processar diferentes tipos de transação ou extrair outras informações.

Opções de personalização

Embora nosso exemplo seja voltado a vendas de NFT, você pode adaptar facilmente este modelo a diversos casos de uso:

1. Modifique transactionTypes na criação do webhook para acompanhar diferentes eventos
2. Altere accountAddresses para monitorar programas ou carteiras específicos
3. Ajuste a formatação da mensagem no endpoint /webhook conforme suas necessidades de dados
4. Implemente lógica adicional para filtrar ou processar os dados recebidos‍

Explore a documentação de webhooks da Helius para conhecer toda a variedade de dados e eventos que podem ser acompanhados. Mas não se limite apenas aos eventos definidos explicitamente! Os webhooks da Helius são extremamente versáteis e podem acompanhar uma ampla variedade de atividades on-chain, até mesmo aquelas que não são processadas diretamente nem mencionadas em nossa documentação.

Veja alguns exemplos de eventos que você pode acompanhar:

• Transferências de tokens SPL específicos
• Novos deploys de programas
• Criação de pools ou adição de liquidez na Raydium
• Criação de propostas de governança ou votações
• Lançamentos de candy machines da Metaplex
• Criação de mercados na Serum

Com este modelo, você pode criar bots do Telegram para uma ampla variedade de tarefas de monitoramento da Solana, desde eventos de protocolos DeFi até o acompanhamento de atividades de carteiras e muito mais.

Se você leu até aqui, agradecemos! Esperamos que este guia tenha ajudado você a dar os primeiros passos na criação do seu próprio bot do Telegram para Solana. Assine nossa newsletter para não perder nenhuma novidade da Solana. Quer se aprofundar? Confira os artigos mais recentes no blog da Helius e continue hoje mesmo sua jornada na Solana.

Recursos adicionais

1. Documentação da Helius
2. Documentação do Cloudflare Workers
3. API de bots do Telegram
4. Documentação do Hono