> ## 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.

# 토큰 계정 (ATA) 필터링

> 토큰 계정(ATA) 확장을 통해 LaserStream gRPC 스트림에서 지갑의 들어오는 SPL 토큰 전송을 포착합니다 — 단순 accountInclude 필터가 놓치는 소유자 기반 매칭.

LaserStream의 `tokenAccounts` 필터는 gRPC 트랜잭션 구독이 지갑의 퍼브키가 직접 나타나는 트랜잭션뿐만 아니라 \*\*지갑이 소유한 연관된 토큰 계정(ATA)\*\*의 활동을 매칭할 수 있게 합니다. 동일한 필터가 WebSocket에서도 사용 가능합니다 — [토큰 계정 (ATA) 필터링 over WebSocket](/docs/ko/rpc/websocket/token-account-filtering)을 참조하세요.

## 문제점: 단순 계정 필터는 들어오는 토큰 전송을 놓칩니다

`accountInclude: [wallet]`으로 지갑을 감시할 때, 해당 지갑의 퍼브키가 트랜잭션의 계정 키에 나타나는 트랜잭션만 매칭됩니다. 일반적인 사례는 놓치기 쉽습니다: 누군가 지갑에 SPL 토큰(예: USDC)을 전송할 때, 전송은 지갑의 **연관된 토큰 계정(ATA)** — 별도의 프로그램 파생 주소 — 을 터치하지만 지갑의 퍼브키 자체는 아닙니다.

따라서 단순 `accountInclude: [wallet]` 구독은 들어오는 토큰 전송을 절대 보지 못합니다. 사전에 지갑이 소유한 모든 ATA를 열거하고 각각을 필터에 추가해야 합니다 — 그러나 ATAs는 필요에 따라 생성되므로(하나의 민트당 하나씩), 사전에 전체 세트를 알 수 없습니다.

## `tokenAccounts` 확장 작동 방식

트랜잭션 필터에 `tokenAccounts`를 설정하여 매칭을 확장하면 `accountInclude` 지갑이 소유한 토큰 계정을 터치하는 트랜잭션도 매칭됩니다. 매칭은 **소유자 기반**입니다: LaserStream은 매칭 시점에 `accountInclude` 주소가 소유한 토큰 계정을 해결하므로 지갑이 소유한 모든 토큰 계정을 포착합니다 — 비정형도 포함하여, 파생된 ATA 주소만이 아닙니다. 직접 ATA를 나열할 필요가 없습니다.

`tokenAccounts`를 생략한 구독은 정확히 이전과 동일하게 작동하므로, 기존 필터에 안전하게 추가할 수 있습니다.

## 확장 모드

`tokenAccounts`는 세 개의 문자열 값 중 하나를 취합니다:

| 값                  | 매칭                                         | 볼륨            | 사용 용도                                    |
| ------------------ | ------------------------------------------ | ------------- | ---------------------------------------- |
| `"balanceChanged"` | 소유한 토큰 잔액이 실제로 변경된(또는 토큰 계정이 닫힌) 트랜잭션      | 더 낮음 — 추천 기본값 | "실제 자금이 이동했을 때 알려주세요" — 지갑에 정산되는 입출금, 스왑 |
| `"all"`            | 잔액이 변경되지 않았더라도 지갑이 소유한 토큰 계정을 참조하는 모든 트랜잭션 | 더 높음          | 지갑의 토큰 계정을 최소한이라도 터치하는 모든 것에 대한 전체 가시성   |
| `"none"`           | 확장 없음 — 필드를 생략한 것과 동일                      | —             | 기본값                                      |

`"balanceChanged"`로 시작하세요. 이는 `"all"` 볼륨의 일부로 실질적인 자금 이동을 포착합니다.

## LaserStream gRPC에서 사용하기

`SubscribeRequest`의 트랜잭션 필터에 `tokenAccounts`를 추가하세요. [Helius LaserStream SDK](/docs/ko/laserstream/clients)는 문자열을 와이어 수준의 `TokenAccountExpansionControlFlag` 열거형으로 변환해줍니다 (`yellowstone-grpc-proto` 12.5.0+의 일부).

```typescript theme={"system"}
import { subscribe, CommitmentLevel, LaserstreamConfig, SubscribeRequest } from 'helius-laserstream';
import bs58 from 'bs58';

const wallet = '<WALLET_PUBKEY>';

const subscriptionRequest: SubscribeRequest = {
  transactions: {
    "wallet-activity": {
      accountInclude: [wallet],
      accountExclude: [],
      accountRequired: [],
      vote: false,
      failed: false,
      tokenAccounts: "balanceChanged" // also match the wallet's ATAs
    }
  },
  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;
  // Token balances this wallet owns that changed in the tx
  const owned = (tx.meta?.postTokenBalances || []).filter((b: any) => b.owner === wallet);
  console.log(bs58.encode(tx.signature), owned);
}, async (error) => {
  console.error('Stream error:', error);
});
```

잔액 전후를 비교하는 전체 예제는 [트랜잭션 모니터링 가이드](/docs/ko/laserstream/guides/transaction-monitoring)를 참조하세요, 각 트랜잭션 필터 필드는 [Subscribe Request reference](/docs/ko/laserstream/grpc)를 확인하세요.

## 매칭된 내용 읽기

ATA 확장을 통해 트랜잭션이 매칭되면, 지갑의 토큰 이동은 트랜잭션의 `meta.postTokenBalances`와 `meta.preTokenBalances`에 존재합니다. 해당 항목을 `owner`로 필터링하여 실제로 소유한 잔액을 분리한 다음, 동일한 `accountIndex`의 `preTokenBalances`와 `postTokenBalances`를 비교하여 각 민트가 얼마나 이동했는지 확인하세요. 위의 예에서 필터링 단계를 보여줍니다; 전체 비교는 [트랜잭션 모니터링 가이드](/docs/ko/laserstream/guides/transaction-monitoring#예시-4-지갑-모니터링토큰-전송-포함)를 참조하세요.

## 관련 항목

<CardGroup cols={2}>
  <Card title="트랜잭션 모니터링" icon="receipt" href="/docs/ko/laserstream/guides/transaction-monitoring">
    전체 필터링 전략과 grpc를 통한 실행 가능한 지갑 감시 예제입니다.
  </Card>

  <Card title="토큰 계정 필터링 (WebSocket)" icon="bolt" href="/docs/ko/rpc/websocket/token-account-filtering">
    WebSocket `transactionSubscribe` 메서드의 동일한 `tokenAccounts` 필드입니다.
  </Card>

  <Card title="구독 요청 참조" icon="filter" href="/docs/ko/laserstream/grpc">
    `tokenAccounts`를 포함한 모든 트랜잭션 필터 필드입니다.
  </Card>

  <Card title="압축 필터" icon="layer-group" href="/docs/ko/laserstream/cuckoo-filters">
    하나의 스트림에서 수십만 개의 계정을 추적하세요.
  </Card>
</CardGroup>