> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# getTransactionStatus

> Fetches the on-chain status of a transaction from StarkNet. Useful for polling until confirmation.

## Usage

```typescript theme={null}
const status = await sdk.getTransactionStatus("0x...", bearerToken);
```

## Parameters

| Parameter     | Type     | Required | Description                                             |
| ------------- | -------- | -------- | ------------------------------------------------------- |
| `hash`        | `string` | Yes      | Transaction hash (`0x...`)                              |
| `bearerToken` | `string` | No       | JWT token. Falls back to `apiSecretKey` if not provided |

## Return Value

Returns a `Promise<TransactionStatusResponse>`:

| Field             | Type                  | Description                         |
| ----------------- | --------------------- | ----------------------------------- |
| `transactionHash` | `string`              | Transaction hash                    |
| `status`          | `OnChainTxStatus`     | Current on-chain status (see below) |
| `blockNumber`     | `number \| undefined` | Block number if included in a block |
| `revertReason`    | `string \| undefined` | Reason if status is `REVERTED`      |

### OnChainTxStatus Values

| Status           | Description                  | Terminal |
| ---------------- | ---------------------------- | -------- |
| `RECEIVED`       | Transaction received by node | No       |
| `PENDING`        | Waiting for inclusion        | No       |
| `ACCEPTED_ON_L2` | Confirmed on StarkNet L2     | No       |
| `ACCEPTED_ON_L1` | Proven on Ethereum L1        | Yes      |
| `REJECTED`       | Rejected by sequencer        | Yes      |
| `REVERTED`       | Execution reverted on-chain  | Yes      |
| `NOT_RECEIVED`   | Not found on network         | Yes      |

## Example

```typescript theme={null}
// Poll for confirmation
const poll = async (hash: string) => {
  const terminalStatuses = ["ACCEPTED_ON_L1", "REJECTED", "REVERTED", "NOT_RECEIVED"];
  const MAX_RETRIES = 60; // 60 retries * 3s = 3 minutes max

  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
    const { status, revertReason } = await sdk.getTransactionStatus(hash, bearerToken);

    if (terminalStatuses.includes(status)) {
      if (status === "REVERTED") console.error("Reverted:", revertReason);
      return status;
    }

    await new Promise((r) => setTimeout(r, 3000));
  }

  throw new Error(`Transaction ${hash} did not reach terminal status after ${MAX_RETRIES} attempts`);
};
```