> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Monitoramento de Transações com LaserStream
> Transmita transações Solana em tempo real com o LaserStream — filtragem de programas, detalhes de execução, alterações de saldo de tokens e reprodução segura de reconexão.
O monitoramento de transações permite que você acompanhe a execução de transações, status de sucesso/falha, interações com programas e mudanças de saldo de tokens na Solana em tempo real. Este guia abrange estratégias de filtragem e implementações práticas usando o SDK [`helius-laserstream`](/docs/pt-BR/laserstream/clients).
**Pré-requisitos:** Este guia assume que você completou o [Quickstart do LaserStream gRPC](/docs/pt-BR/laserstream/grpc) e possui uma chave de API.
***
## Opções de Filtragem de Transação
O LaserStream usa a mesma forma de filtro que o Yellowstone gRPC, incluindo o filtro `tokenAccounts` (expansão ATA). Os campos que você definirá dentro de `transactions.`:
* **`accountInclude`** — corresponde se alguma dessas contas aparecer (ou lógico)
* **`accountRequired`** — corresponde apenas se todas essas contas aparecerem (e lógico)
* **`accountExclude`** — descarta se alguma dessas contas aparecer
* **`vote` / `failed`** — flags booleanos para transações de voto e falhas
* **`tokenAccounts`** — expansão opcional da conta de token associada (ATA) (`"balanceChanged"`, `"all"`, ou `"none"`), então uma carteira `accountInclude` também corresponde a transações onde possui um saldo de token SPL. Veja [Filtragem de Conta de Token (ATA)](/docs/pt-BR/laserstream/token-account-filtering) e a aba **Assistindo uma Carteira** abaixo.
**Monitore transações envolvendo programas específicos**
Acompanhe todas as transações que tocam programas de seu interesse:
```typescript theme={"system"}
import { subscribe, CommitmentLevel, LaserstreamConfig, SubscribeRequest } from 'helius-laserstream';
const subscriptionRequest: SubscribeRequest = {
transactions: {
"program-filter": {
accountInclude: [
"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", // Token Program
"11111111111111111111111111111111", // System Program
"675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8" // Your program
],
accountExclude: [],
accountRequired: [],
vote: false,
failed: false
}
},
commitment: CommitmentLevel.CONFIRMED,
accounts: {},
slots: {},
transactionsStatus: {},
blocks: {},
blocksMeta: {},
entry: {},
accountsDataSlice: [],
};
```
**Melhor para:** Monitoramento específico de programa, rastreamento de protocolo DeFi, interações com contratos inteligentes.
**Monitore transações afetando contas específicas**
```typescript theme={"system"}
const subscriptionRequest: SubscribeRequest = {
transactions: {
"wallet-filter": {
accountInclude: [
"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC mint
"YourWalletAddress" // Your wallet
],
accountExclude: [],
accountRequired: [],
vote: false,
failed: true // Include failures to track errors
}
},
commitment: CommitmentLevel.CONFIRMED,
accounts: {}, slots: {}, transactionsStatus: {},
blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
};
```
**Uso:** Monitoramento de carteira, rastreamento de emissão de token, dashboards de atividade de conta.
**Combine múltiplos critérios de filtragem**
```typescript theme={"system"}
const subscriptionRequest: SubscribeRequest = {
transactions: {
"advanced-filter": {
accountInclude: ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
accountRequired: ["YourProgramId"], // Must include this program
accountExclude: ["VoteProgram"], // Exclude vote-related txs
vote: false,
failed: false
}
},
commitment: CommitmentLevel.CONFIRMED,
accounts: {}, slots: {}, transactionsStatus: {},
blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
};
```
**Lógica de filtragem:** `accountInclude` (OU) **E** `accountRequired` (E) **E NÃO** `accountExclude`.
**Capture transferências de tokens recebidas, não apenas atividade direta**
`accountInclude` só corresponde a transações onde a carteira aparece diretamente nas chaves de conta. Quando alguém envia um token SPL para a carteira, a transferência toca na **conta de token associada (ATA)** da carteira, não na chave pública da carteira — então uma `accountInclude: [wallet]` comum nunca vê isso.
Defina `tokenAccounts` para expandir a correspondência para transações onde a carteira **possui** um saldo de token. Ele aceita uma string:
* **`"balanceChanged"`** — corresponde quando um saldo de token possuído mudou (ou sua conta de token foi fechada). Melhor para "me diga quando o dinheiro realmente se moveu" — mais estreito, menor volume, o padrão recomendado.
* **`"all"`** — corresponde a qualquer transação que faça referência a um saldo de token possuído, mesmo que não alterado. Volume substancialmente maior.
* **`"none"`** — sem expansão (igual a omitir o campo).
```typescript theme={"system"}
const subscriptionRequest: SubscribeRequest = {
transactions: {
"wallet-with-tokens": {
accountInclude: ["YourWalletAddress"],
accountExclude: [],
accountRequired: [],
vote: false,
failed: false,
tokenAccounts: "balanceChanged" // also match the wallet's ATAs
}
},
commitment: CommitmentLevel.CONFIRMED,
accounts: {}, slots: {}, transactionsStatus: {},
blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
};
```
A correspondência é baseada no proprietário — captura qualquer conta de token que a carteira possua (incluindo as não canônicas), não apenas o endereço ATA derivado. O SDK converte a string para o enum de nível de wire `TokenAccountExpansionControlFlag` para você.
***
## Exemplos Práticos
### Exemplo 1: Monitorar Transações de DEX
Acompanhar transações que tocam programas DEX populares:
```typescript [expandable] theme={"system"}
import { subscribe, CommitmentLevel, LaserstreamConfig, SubscribeRequest } from 'helius-laserstream';
import bs58 from 'bs58';
async function monitorDEXTransactions() {
const subscriptionRequest: SubscribeRequest = {
transactions: {
"dex-filter": {
accountInclude: [
"675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8", // Raydium
"CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", // Raydium CLMM
"JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4" // Jupiter
],
accountExclude: [],
accountRequired: [],
vote: false,
failed: false
}
},
commitment: CommitmentLevel.CONFIRMED,
accounts: {}, slots: {}, transactionsStatus: {},
blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
};
const config: LaserstreamConfig = {
apiKey: 'YOUR_API_KEY',
endpoint: 'https://laserstream-mainnet-ewr.helius-rpc.com', // Choose your closest region
};
await subscribe(config, subscriptionRequest, async (data) => {
if (!data.transaction?.transaction) return;
const tx = data.transaction.transaction;
console.log(`\n🔄 DEX Transaction:`);
console.log(` Signature: ${bs58.encode(tx.signature)}`);
console.log(` Slot: ${data.transaction.slot}`);
console.log(` Status: ${tx.meta?.err ? 'Failed' : 'Success'}`);
console.log(` Fee: ${tx.meta?.fee || 0} lamports`);
console.log(` Compute Units: ${tx.meta?.computeUnitsConsumed || 0}`);
// Token balance changes
if (tx.meta?.preTokenBalances?.length > 0) {
console.log(` Token Balance Changes:`);
tx.meta.preTokenBalances.forEach((preBalance: any, index: number) => {
const postBalance = tx.meta.postTokenBalances[index];
if (preBalance && postBalance) {
const change = postBalance.uiTokenAmount.uiAmount - preBalance.uiTokenAmount.uiAmount;
if (change !== 0) {
console.log(` ${preBalance.mint}: ${change > 0 ? '+' : ''}${change}`);
}
}
});
}
}, async (error) => {
console.error('Stream error:', error);
});
}
monitorDEXTransactions().catch(console.error);
```
### Exemplo 2: Monitorar Transações com Falha
Acompanhar transações com falha para identificar problemas de aplicação:
```typescript [expandable] theme={"system"}
async function monitorFailedTransactions() {
const subscriptionRequest: SubscribeRequest = {
transactions: {
"failures": {
accountInclude: ["YourProgramId"],
accountExclude: [],
accountRequired: [],
vote: false,
failed: true // Only failed transactions
}
},
commitment: CommitmentLevel.CONFIRMED,
accounts: {}, slots: {}, transactionsStatus: {},
blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
};
const config: LaserstreamConfig = {
apiKey: 'YOUR_API_KEY',
endpoint: 'https://laserstream-mainnet-ewr.helius-rpc.com',
};
await subscribe(config, subscriptionRequest, async (data) => {
if (!data.transaction?.transaction?.meta?.err) return;
const tx = data.transaction.transaction;
console.log(`\n❌ Failed Transaction:`);
console.log(` Signature: ${bs58.encode(tx.signature)}`);
console.log(` Slot: ${data.transaction.slot}`);
console.log(` Error: ${JSON.stringify(tx.meta.err)}`);
console.log(` Fee: ${tx.meta.fee} lamports`);
console.log(` Compute Units: ${tx.meta.computeUnitsConsumed || 0}`);
}, async (error) => {
console.error('Stream error:', error);
});
}
```
### Exemplo 3: Monitorar Transações de Alto Valor
Acompanhar transações com transferências significativas de SOL:
```typescript [expandable] theme={"system"}
async function monitorHighValueTransactions() {
const subscriptionRequest: SubscribeRequest = {
transactions: {
"system-program": {
accountInclude: ["11111111111111111111111111111111"],
accountExclude: [],
accountRequired: [],
vote: false,
failed: false
}
},
commitment: CommitmentLevel.CONFIRMED,
accounts: {}, slots: {}, transactionsStatus: {},
blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
};
const config: LaserstreamConfig = {
apiKey: 'YOUR_API_KEY',
endpoint: 'https://laserstream-mainnet-ewr.helius-rpc.com',
};
await subscribe(config, subscriptionRequest, async (data) => {
if (!data.transaction?.transaction?.meta) return;
const tx = data.transaction.transaction;
const preBalances = tx.meta.preBalances || [];
const postBalances = tx.meta.postBalances || [];
let maxChange = 0;
preBalances.forEach((preBalance: number, index: number) => {
const postBalance = postBalances[index] || 0;
maxChange = Math.max(maxChange, Math.abs(postBalance - preBalance));
});
const changeInSOL = maxChange / 1e9;
if (changeInSOL > 10) {
console.log(`\n💰 High-Value Transaction:`);
console.log(` Signature: ${bs58.encode(tx.signature)}`);
console.log(` Slot: ${data.transaction.slot}`);
console.log(` Max SOL Transfer: ${changeInSOL.toFixed(2)} SOL`);
console.log(` Fee: ${tx.meta.fee / 1e9} SOL`);
}
}, async (error) => {
console.error('Stream error:', error);
});
}
```
### Exemplo 4: Assistir uma Carteira (incl. transferências de tokens)
Monitore tudo que movimenta dinheiro para uma carteira — incluindo transferências recebidas de tokens SPL que tocam suas ATAs — adicionando `tokenAccounts` a um filtro `accountInclude` comum:
```typescript [expandable] theme={"system"}
import { subscribe, CommitmentLevel, LaserstreamConfig, SubscribeRequest } from 'helius-laserstream';
import bs58 from 'bs58';
async function watchWallet(wallet: string) {
const subscriptionRequest: SubscribeRequest = {
transactions: {
"wallet-activity": {
accountInclude: [wallet],
accountExclude: [],
accountRequired: [],
vote: false,
failed: false,
// Also match txs touching token accounts this wallet owns.
// "balanceChanged" = only when an owned token balance actually moved.
tokenAccounts: "balanceChanged"
}
},
commitment: CommitmentLevel.CONFIRMED,
accounts: {}, slots: {}, transactionsStatus: {},
blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
};
const config: LaserstreamConfig = {
apiKey: 'YOUR_API_KEY',
endpoint: 'https://laserstream-mainnet-ewr.helius-rpc.com',
};
await subscribe(config, subscriptionRequest, async (data) => {
if (!data.transaction?.transaction) return;
const tx = data.transaction.transaction;
console.log(`\n👛 Wallet activity:`);
console.log(` Signature: ${bs58.encode(tx.signature)}`);
console.log(` Slot: ${data.transaction.slot}`);
// Surface token balances this wallet owns that changed in the tx
const owned = (tx.meta?.postTokenBalances || []).filter((b: any) => b.owner === wallet);
owned.forEach((post: any) => {
const pre = (tx.meta.preTokenBalances || []).find(
(b: any) => b.accountIndex === post.accountIndex
);
const before = pre?.uiTokenAmount?.uiAmount || 0;
const after = post.uiTokenAmount?.uiAmount || 0;
if (after !== before) {
console.log(` ${post.mint}: ${after - before > 0 ? '+' : ''}${after - before}`);
}
});
}, async (error) => {
console.error('Stream error:', error);
});
}
```
***
## Estrutura de Dados de Transação
```typescript theme={"system"}
{
signature: string;
isVote: boolean;
transaction: {
message: {
accountKeys: string[]; // All accounts involved
instructions: Instruction[]; // Program instructions
recentBlockhash: string;
};
signatures: string[];
};
meta: {
err: any; // Error details if failed
fee: number; // Transaction fee in lamports
computeUnitsConsumed: number;
preBalances: number[];
postBalances: number[];
preTokenBalances: TokenBalance[];
postTokenBalances: TokenBalance[];
logMessages: string[];
};
}
```
```typescript theme={"system"}
{
accountIndex: number;
mint: string;
owner: string;
uiTokenAmount: {
amount: string;
decimals: number;
uiAmount: number;
uiAmountString: string;
};
}
```
```typescript theme={"system"}
{
programIdIndex: number; // Index in accountKeys array
accounts: number[];
data: string; // Instruction data (base58)
}
```
***
## Referência de Lógica de Filtragem
**`accountInclude`:** A transação deve envolver QUALQUER uma dessas contas.
`["A", "B"]` corresponde a transações envolvendo a conta A OU a conta B.
**`accountRequired`:** A transação deve envolver TODAS essas contas.
`["A", "B"]` corresponde a transações envolvendo a conta A E a conta B.
**`accountExclude`:** A transação NÃO deve envolver nenhuma dessas contas.
Filtro final: `(accountInclude OR empty) AND (accountRequired AND all) AND NOT (accountExclude OR any)`.
***
## Considerações de Desempenho
Streams de transações podem ser de alto volume. Para manter o ritmo:
* Comece com filtros específicos de programa (não assine "todas as transações")
* Use `confirmed` ao invés de `processed` quando puder tolerar \~1.5s de latência extra
* Monitore sua capacidade de processamento com um contador
* Considere executar consumidores paralelos por trás de uma fila
```typescript theme={"system"}
let count = 0;
const startTime = Date.now();
// inside your subscribe handler:
count++;
if (count % 100 === 0) {
const elapsed = (Date.now() - startTime) / 1000;
console.log(`Processing ${(count / elapsed).toFixed(1)} tx/sec`);
}
```
Extraia apenas o que você precisa para manter a memória baixa:
```typescript theme={"system"}
import bs58 from 'bs58';
function extractTransactionData(tx: any) {
return {
signature: bs58.encode(tx.signature),
slot: tx.slot,
success: !tx.meta?.err,
fee: tx.meta?.fee || 0,
computeUnits: tx.meta?.computeUnitsConsumed || 0,
};
}
```
***
## Tratamento de Erros
**Sintoma:** Volume de transações avassalador.
**Soluções:** Adicione filtros mais rigorosos (`accountRequired`, `accountExclude`); use comprometimento mais alto; implemente amostragem ou limitação de taxa; processe assincronamente.
**Sintoma:** Transações esperadas não aparecem.
**Soluções:** Verifique se os endereços dos programas estão corretos; confira se as transações realmente existem; experimente `processed` para atualizações mais rápidas; alivie filtros `accountRequired`/`accountExclude` restritivos.
**Sintoma:** Não consegue analisar dados de transação.
**Soluções:** Lide com campos ausentes graciosamente; valide a estrutura antes de processar; envolva a análise em try/catch; veja [Decodificando Dados de Transação](/docs/pt-BR/laserstream/guides/decoding-transaction-data).
***
## Próximos Passos
Acompanhe o consenso da rede e a produção de blocos.
Exemplo do mundo real: monitore transações Pump.fun AMM.
Analise as cargas de transação binárias em transações legíveis de Solana.
O mesmo fluxo de trabalho contra o protocolo gRPC Yellowstone bruto.