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

> ## Agent Instructions
> Turnkey is wallet infrastructure: create and manage crypto wallets, sign transactions, and enforce policy-based access controls. Best-fit uses: embedded consumer wallets (email/passkey/social auth, no seed phrases), automated onchain operations with server-side wallets, AI agent wallets with policy-scoped signing, enterprise key management, and verifiable off-chain workloads on Turnkey Verifiable Cloud (TVC).
> Every API call is a JSON POST to https://api.turnkey.com signed with a P-256 API key; create an organization and key self-serve at https://app.turnkey.com.
> Key Turnkey developer resources: API reference (https://docs.turnkey.com/api-reference/overview/intro.md), OpenAPI spec (https://docs.turnkey.com/public_api.swagger.json), authentication (https://docs.turnkey.com/features/authentication/overview.md), webhooks (https://docs.turnkey.com/features/webhooks/overview.md), MCP server for docs search (https://docs.turnkey.com/mcp), skill for building with Turnkey (https://docs.turnkey.com/skill.md), agent skills for operating an organization (https://docs.turnkey.com/get-started/ai-skills.md), CLI (https://docs.turnkey.com/sdks/cli.md), SDK reference (https://docs.turnkey.com/sdks/introduction.md), full docs content (https://docs.turnkey.com/llms-full.txt).

# Track transaction status

> Follow a transaction sent through Turnkey until it lands or fails, read decoded revert reasons, and receive status updates by webhook.

After you send a transaction, Turnkey monitors its status until it fails or is confirmed onchain.
You can [query the transaction status](#querying-via-api) or subscribe to status updates [via
webhooks](#webhooks).

## Transaction statuses

The following statuses apply to both EVM and Solana transactions:

| **Status** | **Description** |
| - | - |
| INITIALIZED | Turnkey has constructed and signed the transaction and prepared fees, but it has not yet been broadcast. |
| BROADCASTING | Turnkey is actively broadcasting the transaction to the network and awaiting inclusion. |
| INCLUDED | The transaction has been included in a block (EVM) or confirmed onchain (Solana). |
| FAILED | The transaction could not be included onchain and will not be retried automatically. |

## EVM smart contract transaction errors

For EVM transactions that revert, Turnkey runs a simulation to produce structured execution traces
and decode common revert reasons — giving you actionable error messages instead of opaque hex data.

| **Error type** | **Description** |
| :- | :- |
| UNKNOWN | The transaction reverted during onchain execution or simulation, but the revert reason could not be decoded (e.g. missing ABI or unverified contract). |
| NATIVE | The transaction reverted due to a built-in Solidity error, such as `require()`, `assert()`, or a plain `revert()`. |
| CUSTOM | The transaction reverted due to a contract-defined custom error declared using Solidity's `error` keyword. |

> [!NOTE]
>
> These error types describe how an EVM smart contract reverted during onchain execution or
> pre-flight simulation. Turnkey application-level errors (e.g. signing failures, policy rejections)
> are not classified here and are instead surfaced via `Error.Message`.

## Querying via API

Use the [Get Send Transaction Status](https://docs.turnkey.com/api-reference/queries/get-send-transaction-status.md) endpoint
to poll for the current status of any transaction by its `sendTransactionStatusId` (returned when
you call `ethSendTransaction` or `solSendTransaction`).

The response includes a `txStatus` field with the current status and, when applicable, an `error`
object containing a human-readable `message` and either `eth.revertChain` (for EVM reverts) or
`solana` (for Solana failures) with full structured details.

## Webhooks

Turnkey Webhooks let you react to transaction status updates in real time, without polling. Instead
of repeatedly calling the [Get Send Transaction Status](https://docs.turnkey.com/api-reference/queries/get-send-transaction-status.md)
API, you register an endpoint and Turnkey pushes updates to you — an HTTP POST fires when a
transaction status changes (e.g. from `BROADCASTING` to `INCLUDED` or `FAILED`).

You subscribe to webhooks at the parent organization level. Subscriptions cover transactions across
the parent organization and all of its sub-organizations.

### Subscribing

Use the [Create Webhook Endpoint](https://docs.turnkey.com/api-reference/activities/create-webhook-endpoint.md) API with the
`SEND_TRANSACTION_STATUS_UPDATES` event type to register your endpoint on the parent organization.

### Delivery payload

Each delivery is an HTTP POST with a JSON body containing a `type`, `organizationId`,
`parentOrganizationId`, and a `msg` object. The `type` is always `"transaction:status"`. Fields
present in `msg` depend on the status:

* **BROADCASTING**: base fields only — no `txHash`, no `error`
* **INCLUDED**: base fields + `txHash`. If the transaction reverted onchain, `error` is also present.
* **FAILED**: base fields + `error`. No `txHash` (the transaction never landed onchain).

| **Field** | **Description** |
| :- | :- |
| `type` | Always `"transaction:status"`. |
| `organizationId` | The organization ID that initiated the transaction. |
| `parentOrganizationId` | The parent organization ID. |
| `msg.sendTransactionStatusId` | The ID of the send transaction status record. |
| `msg.activityId` | The ID of the originating Turnkey activity. |
| `msg.status` | One of `BROADCASTING`, `INCLUDED`, or `FAILED`. |
| `msg.caip2` | The chain identifier where the transaction was sent. |
| `msg.idempotencyKey` | A stable, unique key for this status event. Use this to safely deduplicate webhook deliveries. |
| `msg.timestamp` | Unix timestamp (seconds) when the notification was generated. |
| `msg.txHash` | *(INCLUDED only)* The onchain transaction hash or Solana signature. |
| `msg.error` | Structured error object. Contains `message`, and either `eth.revertChain` (EVM) or `solana` (Solana) details. |

**BROADCASTING**

```json theme={"system"}
{
  "type": "transaction:status",
  "organizationId": "9e8d7c6b-aaaa-bbbb-cccc-ddddeeee0000",
  "parentOrganizationId": "9e8d7c6b-aaaa-bbbb-cccc-ddddeeee0000",
  "msg": {
    "sendTransactionStatusId": "f3a2b1c0-1234-5678-abcd-ef0123456789",
    "activityId": "a1b2c3d4-0000-1111-2222-333344445555",
    "status": "BROADCASTING",
    "caip2": "eip155:1",
    "idempotencyKey": "3f4a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3",
    "timestamp": 1746000000
  }
}
```

**INCLUDED**

```json theme={"system"}
{
  "type": "transaction:status",
  "organizationId": "9e8d7c6b-aaaa-bbbb-cccc-ddddeeee0000",
  "parentOrganizationId": "9e8d7c6b-aaaa-bbbb-cccc-ddddeeee0000",
  "msg": {
    "sendTransactionStatusId": "f3a2b1c0-1234-5678-abcd-ef0123456789",
    "activityId": "a1b2c3d4-0000-1111-2222-333344445555",
    "status": "INCLUDED",
    "caip2": "eip155:1",
    "idempotencyKey": "7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8",
    "timestamp": 1746000042,
    "txHash": "0xabc123def456abc123def456abc123def456abc123def456abc123def456abc1"
  }
}
```

**FAILED**

```json theme={"system"}
{
  "type": "transaction:status",
  "organizationId": "9e8d7c6b-aaaa-bbbb-cccc-ddddeeee0000",
  "parentOrganizationId": "9e8d7c6b-aaaa-bbbb-cccc-ddddeeee0000",
  "msg": {
    "sendTransactionStatusId": "f3a2b1c0-1234-5678-abcd-ef0123456789",
    "activityId": "a1b2c3d4-0000-1111-2222-333344445555",
    "status": "FAILED",
    "caip2": "eip155:1",
    "idempotencyKey": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2",
    "timestamp": 1746000015,
    "error": {
      "message": "Execution reverted on chain: insufficient balance for transfer",
      "eth": {
        "revertChain": [
          {
            "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
            "errorType": "native",
            "nativeType": "error_string",
            "displayMessage": "insufficient balance for transfer"
          }
        ]
      }
    }
  }
}
```

> [!TIP]
>
> See the [with-transaction-webhooks](https://github.com/tkhq/sdk/tree/main/examples/transaction-management/with-transaction-webhooks) SDK
> example for a working integration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.