Skip to main content
After you send a transaction, Turnkey monitors its status until it fails or is confirmed onchain. You can query the transaction status or subscribe to status updates via webhooks.

Transaction statuses

The following statuses apply to both EVM and Solana transactions:

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.
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 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 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 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).
BROADCASTING
INCLUDED
FAILED
See the with-transaction-webhooks SDK example for a working integration.