Broadcasting

Transaction construction, broadcast, and status monitoring for EVM and Solana.

Construction and Broadcast

EVM

A successful EVM transaction requires:

• Transaction construction: assembling the payload (recipient, value, calldata)
• Nonce: set correctly to order transactions and prevent conflicts
• Gas and tip fee: estimated to ensure inclusion even during network congestion
• Signature: cryptographically signing the transaction with the sender’s private key
• Broadcast: submitting the signed transaction to the network and monitoring for inclusion

Turnkey handles all of this for you via ethSendTransaction. Whether or not you use sponsorship, you pass through minimal payloads and we take care of the rest. We auto-fill any fields you omit.

This endpoint supports arbitrary EVM transactions — not just simple sends. You can interact with smart contracts, deploy contracts, or execute any valid EVM operation.

Solana

A successful Solana transaction requires:

• Transaction construction: assembling the list of instructions (program, accounts, data)
• Recent blockhash: fetched and attached at broadcast time to ensure the transaction is valid
• Compute unit limit: estimated and set to prevent failed transactions due to insufficient compute
• Priority fee: set to ensure timely inclusion under current network conditions
• Signature: cryptographically signing the transaction with the sender’s private key
• Broadcast: submitting the signed transaction to the network and monitoring for confirmation

Turnkey handles all of this for you via solSendTransaction. Whether or not you use sponsorship, you pass through a minimal payload and we manage the rest.

On Solana, fee sponsorship and rent sponsorship are separate. Sponsor Solana Rent is disabled by default and must be enabled in the dashboard before Turnkey will pre-fund rent for account creation. If created accounts are later closed, refunded rent can go back to the signer rather than the sponsor. See Solana Rent Sponsorship. For payer behavior, static-key requirements, and account-creation caveats in sponsored flows, see Solana transaction construction for sponsored flows.

Transaction status and enriched errors

After you send a transaction, Turnkey monitors its status until it fails or is confirmed on-chain. 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:

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 on-chain (Solana).
FAILED	The transaction could not be included on-chain 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 on-chain 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.

These error types describe how an EVM smart contract reverted during on-chain 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 with the same structure as the error field in webhook payloads — 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 to check for updates, you register an endpoint and Turnkey pushes the data to you; an HTTP POST fires when a transaction status changes (e.g. from BROADCASTING to INCLUDED or FAILED). Webhook payloads deliver rich transaction status updates as soon as they occur, so you can keep your users informed and react to failures immediately.

You subscribe to webhooks at the parent organization level. Subscriptions cover all transactions initiated across the parent organization and all of its sub-organizations. In other words, once you subscribe you’ll receive webhook notifications for all transactions within your entire Turnkey instance.

Subscribing

Use the Create Webhook Endpoint API with the SEND_TRANSACTION_STATUS_UPDATES event type to register your endpoint. Create the webhook endpoint on the parent organization. Balance webhook delivery is scoped to wallet-account addresses within your parent organization and its sub-organizations. This includes both addresses generated through Turnkey and addresses imported into your Turnkey organization.

Delivery payload

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

• BROADCASTING: base fields only — no txHash, no error
• INCLUDED: base fields + txHash. If the transaction was included but reverted on-chain, error is also present with full revert details.
• FAILED: base fields + error. No txHash (the transaction never landed on-chain).

Field	Description
type	Always "transaction:status".
msg.sendTransactionStatusId	The ID of the send transaction status record.
msg.activityId	The ID of the originating Turnkey activity.
msg.orgID	The sub-organization ID that initiated the transaction.
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 on-chain transaction hash or Solana signature.
msg.error	(FAILED only) Structured error object. Contains message, and either eth.revertChain (EVM) or solana (Solana) details.

BROADCASTING

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

INCLUDED

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

FAILED

{
  "type": "transaction:status",
  "msg": {
    "sendTransactionStatusId": "f3a2b1c0-1234-5678-abcd-ef0123456789",
    "activityId": "a1b2c3d4-0000-1111-2222-333344445555",
    "orgID": "9e8d7c6b-aaaa-bbbb-cccc-ddddeeee0000",
    "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"
          }
        ]
      }
    }
  }
}

See the with-balance-confirmed-webhooks SDK example for a working integration.