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

# getSignatureStatuses 사용법

> getSignatureStatuses 사용 사례, 코드 예제, 요청 매개변수, 응답 구조 및 팁을 학습합니다.

[`getSignatureStatuses`](https://www.helius.dev/docs/api-reference/rpc/http/getsignaturestatuses) RPC 메소드를 사용하면 트랜잭션 서명의 목록에 대한 처리 및 확인 상태를 조회할 수 있습니다. 이는 네트워크에 의해 [처리, 확인 또는 완료](https://www.helius.dev/blog/solana-commitment-levels) 되었는지 여부를 확인하는 데 유용합니다.

`searchTransactionHistory` 옵션이 활성화되지 않는 한, 이 메소드는 주로 RPC 노드의 최근 상태 캐시를 쿼리합니다. 오래된 트랜잭션의 경우 `searchTransactionHistory`을 활성화하는 것이 중요합니다.

<Warning>
  **더 나은 성능을 위해 배칭을 피하세요**

  보관 메소드의 배칭은 지연 시간을 크게 증가시킵니다. 10개 이상의 요청을 초과하는 배치는 허용되지 않습니다.
</Warning>

## 일반적인 사용 사례

* **거래 완료 확인:** 제출된 트랜잭션이 원하는 수준의 확인에 도달했는지 확인합니다 (예: `confirmed` 또는 `finalized`).
* **배치 상태 조회:** 배치 전송 후 여러 트랜잭션 상태를 효율적으로 확인합니다.
* **트랜잭션 상태에 따른 UI 업데이트:** 사용자에게 트랜잭션의 실시간 상태를 반영합니다.
* **오류 확인:** 트랜잭션 목록 중 실패한 항목이 있는지 및 그 이유를 식별합니다.

## 요청 매개변수

1. **`signatures`** (`array` of `string`): (필수) base-58로 인코딩된 트랜잭션 서명의 배열입니다. 한 번의 요청으로 최대 256개의 서명을 쿼리할 수 있습니다.
2. **`options`** (`object`, 선택적): 다음 필드를 포함한 선택적 구성 객체:
   * **`searchTransactionHistory`** (`boolean`, 선택적): `true`이면 RPC 노드는 전체 트랜잭션 기록을 검색하여 서명을 찾습니다. `false` (기본값)인 경우 최근 상태 캐시만 검색합니다. 오래되거나 잠재적으로 삭제된 트랜잭션의 경우, 이를 `true`으로 설정하십시오.

## 응답 구조

JSON-RPC 응답의 `result` 필드는 두 개의 필드를 포함하는 객체를 포함합니다:

* **`context`** (`object`): 다음을 포함하는 객체:
  * **`slot`** (`u64`): RPC 노드가 이 요청을 처리한 슬롯.
* **`value`** (`array` of `object` | `null`): 요청의 서명 순서에 해당하는 상태 객체의 배열. 각 요소는 다음과 같을 수 있습니다:
  * 서명이 발견된 경우 다음 필드가 포함된 **객체**:
    * **`slot`** (`u64`): 트랜잭션이 처리된 슬롯.
    * **`confirmations`** (`number` | `null`): 트랜잭션이 처리된 이후 확인된 블록 수. 트랜잭션이 완료되면 `null`입니다 (확정성은 롤백되지 않고 특정 확인 수는 덜 중요하게 됩니다).
    * **`err`** (`object` | `null`): 트랜잭션 실패 시 오류 객체 (예: `{"InstructionError":[0,{"Custom":1}]}`), 성공 시 `null`.
    * **`status`** (`object`): 트랜잭션 실행 상태를 나타내는 객체. 일반적으로 성공한 트랜잭션에는 `{"Ok":null}`, 실패한 경우에는 오류를 자세히 설명하는 객체.
    * **`confirmationStatus`** (`string` | `null`): 트랜잭션에 대한 클러스터의 확인 상태 (예: `processed`, `confirmed`, `finalized`). 캐시에서 상태를 사용할 수 없고 `searchTransactionHistory`가 거짓인 경우 `null`일 수 있습니다.
  * **`null`**: 서명이 상태 캐시에 없고 `searchTransactionHistory`가 `false` (또는 기록 검색에서도 실제로 존재하지 않는 경우).

## 예제

### 1. 서명 목록에 대한 상태 가져오기 (최근 캐시)

이 예제는 노드의 최근 캐시를 활용하여 두 서명의 상태를 가져옵니다.

<CodeGroup>
  ```bash cURL theme={"system"}
  # Replace <api-key> with your Helius API key
  # Replace with actual transaction signatures
  curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getSignatureStatuses",
      "params": [
        [
          "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
          "2x5YfV29N4p9K2kEFK2gFfC5T5acbs2z2MytTZqrgq17pYjCMfYjW4sAUpkWMkMzxGztD2Qv5v7n92uYJcQY9c7a" 
        ]
      ]
    }'
  ```

  ```javascript JavaScript (using @solana/web3.js) theme={"system"}
  // Replace <api-key> with your Helius API key
  const { Connection } = require('@solana/web3.js');

  async function checkRecentSignatures() {
    const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
    const signatures = [
      '5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW',
      '2x5YfV29N4p9K2kEFK2gFfC5T5acbs2z2MytTZqrgq17pYjCMfYjW4sAUpkWMkMzxGztD2Qv5v7n92uYJcQY9c7a' // Replace with another signature
    ];

    try {
      const response = await connection.getSignatureStatuses(signatures);
      console.log("RPC Response Context Slot:", response.context.slot);
      response.value.forEach((status, index) => {
        console.log(`--- Status for Signature ${index + 1} (${signatures[index].substring(0,10)}...) ---`);
        if (status) {
          console.log(`  Slot: ${status.slot}`);
          console.log(`  Confirmations: ${status.confirmations === null ? 'Finalized (or N/A)' : status.confirmations}`);
          console.log(`  Error: ${JSON.stringify(status.err)}`);
          console.log(`  Execution Status: ${JSON.stringify(status.status)}`);
          console.log(`  Confirmation Status: ${status.confirmationStatus}`);
        } else {
          console.log('  Status not found (likely not in recent cache or does not exist).');
        }
      });
    } catch (error) {
      console.error('Error fetching signature statuses:', error);
    }
  }

  checkRecentSignatures();
  ```
</CodeGroup>

### 2. 트랜잭션 기록 검색을 통한 상태 가져오기

이 예제는 서명에 대한 상태를 검색하고 노드가 트랜잭션 기록을 검색하도록 명시적으로 요청합니다.

<CodeGroup>
  ```bash cURL theme={"system"}
  # Replace <api-key> with your Helius API key
  # Replace with actual transaction signatures
  curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
    '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "getSignatureStatuses",
      "params": [
        [
          "3jPTfHcbzWHeD4jW8q4Y8g3h2D1aBwM81y1sHhDqYQ7Z9x5n7cVy2gD8QWbK9eXwSjJ6aA7FzV2kLpQoEwU9jX", 
          "4SyzjM2fTALqTNjLKMM1yG1bW7kCFu2GvEkKcvKChG9o1KjQW8jLdZ6sWfN9mP1pU3rD7XvA6B2CjHkLwRzYxTnX"  
        ],
        {
          "searchTransactionHistory": true
        }
      ]
    }'
  ```

  ```javascript JavaScript (using @solana/web3.js) theme={"system"}
  // Replace <api-key> with your Helius API key
  const { Connection } = require('@solana/web3.js');

  async function checkSignaturesWithHistory() {
    const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
    const signatures = [
      // Replace with a signature you know is older or might have been dropped
      '3jPTfHcbzWHeD4jW8q4Y8g3h2D1aBwM81y1sHhDqYQ7Z9x5n7cVy2gD8QWbK9eXwSjJ6aA7FzV2kLpQoEwU9jX',
      // Replace with another valid signature
      '4SyzjM2fTALqTNjLKMM1yG1bW7kCFu2GvEkKcvKChG9o1KjQW8jLdZ6sWfN9mP1pU3rD7XvA6B2CjHkLwRzYxTnX' 
    ];

    try {
      const response = await connection.getSignatureStatuses(signatures, { searchTransactionHistory: true });
      console.log("RPC Response Context Slot:", response.context.slot);
      response.value.forEach((status, index) => {
        console.log(`--- Status for Signature ${index + 1} (${signatures[index].substring(0,10)}...) ---`);
        if (status) {
          console.log(`  Slot: ${status.slot}`);
          console.log(`  Confirmations: ${status.confirmations === null ? 'Finalized (or N/A)' : status.confirmations}`);
          console.log(`  Error: ${JSON.stringify(status.err)}`);
          console.log(`  Execution Status: ${JSON.stringify(status.status)}`);
          console.log(`  Confirmation Status: ${status.confirmationStatus}`);
        } else {
          console.log('  Status not found (even with history search, it might not exist or is too old).');
        }
      });
    } catch (error) {
      console.error('Error fetching signature statuses with history:', error);
    }
  }

  checkSignaturesWithHistory();
  ```
</CodeGroup>

## 개발자 팁

* **`searchTransactionHistory`:** 신뢰성을 위해 중요합니다. `false` (기본값)인 경우, 메소드는 제한된 최근 캐시만 확인합니다. 트랜잭션이 오래되었거나 잠재적으로 삭제되었고 이 캐시에 없는 경우, 해당 서명의 상태에 대해 `null`을 반환합니다. 매우 최근이 아닐 수도 있는 트랜잭션의 상태를 확인해야 하는 경우 항상 `true`으로 설정하십시오.
* **서명 제한:** 호출당 최대 256개의 서명을 쿼리할 수 있습니다.
* **`null` 상태:** 주어진 서명의 `value` 배열에서 `null`은 해당 상태를 찾을 수 없었음을 의미합니다. 이는 최근 캐시에 없기 때문일 수 있습니다 (`searchTransactionHistory`가 거짓인 경우), 트랜잭션이 결코 기록되지 않았거나 `searchTransactionHistory: true`와도 노드의 기록에 너무 오래되었을 수 있습니다.
* **`confirmations: null`**: 이는 일반적으로 트랜잭션이 `finalized` 상태에 도달했음을 의미합니다. 이 시점에서는 블록이 되돌릴 수 없다고 간주되기 때문에 특정 확인 수 개념은 덜 중요해집니다.
* **오류 처리:** 트랜잭션이 실패했는지 확인하려면 각 상태 객체 내의 `err` 필드를 확인하십시오. `status` 필드는 또한 세부 정보를 제공할 것입니다 (예: `{"Err":...}`).

`getSignatureStatuses`을 사용하면 여러 Solana 트랜잭션의 상태를 모니터링하는 효율적인 방법입니다. 안정적인 상태 확인을 위해 `searchTransactionHistory: true`을 사용하세요.