Balances

Learn about Turnkey’s balance querying and balance change webhooks.

Overview

Turnkey provides two complementary tools for tracking onchain balances:

• Balances API: query the current balances for a given address on a specific chain, across all supported assets for that chain.
• Balance webhooks: receive notifications when a transaction that includes a balance change is first seen in a block onchain ("balances:confirmed"), or when the containing block has reached the finalization threshold ("balances:finalized").

Concepts

Balances API

The Get Balances endpoint returns all non-zero balances for a given address on a specified chain. You can also call List Supported Assets to retrieve the full catalog of assets available for querying on a given chain, including a logo URL for each asset.

Each balance entry includes the asset metadata (symbol, name, decimals, and CAIP-19 identifier) and the current amount held at the address.

See the with-balances SDK example for a working integration.

The address must belong to a wallet account in your organization. Private key addresses are not supported.

Supported chains

EVM:

• Base - eip155:8453
• Polygon - eip155:137
• Ethereum - eip155:1
• Arbitrum - eip155:42161

EVM testnets:

• Base (Sepolia) - eip155:84532
• Polygon (Amoy) - eip155:80002
• Ethereum (Sepolia) - eip155:11155111
• Arbitrum (Sepolia) - eip155:421614

Solana:

• Solana mainnet - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp (alias: solana:mainnet)
• Solana devnet - solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 (alias: solana:devnet)

Interested in a chain or asset that isn’t listed? Reach out to us!

Webhooks

Turnkey Webhooks let you react to balance changes in real time, without polling. Instead of repeatedly calling the Get Balances API to check for updates, you register an endpoint and Turnkey pushes the data to you. Each payload carries the balance diff for that event (asset, address, and amount transferred), so your application can update state immediately without an additional API call. Combined with the Balance APIs, you have everything you need to keep your application’s balances up to date without building your own indexing/polling infrastructure or relying on another third party.

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

The two-webhook model

Turnkey emits two event types for every balance change:

• "balances:confirmed" fires when a supported asset transfer is first included in a block onchain. The transfer has happened, but a chain reorganization could still remove it from the canonical chain.
• "balances:finalized" fires once the containing block has reached the finalization threshold for that chain. At this point the chance of the transfer being removed by a reorg is negligible.

You can subscribe to one or both. For example, a consumer app that wants its UI to react immediately can listen on "balances:confirmed", render the deposit as pending, and clear that state when the matching "balances:finalized" arrives. An application moving high-value transfers that needs certainty before crediting funds can ignore "balances:confirmed" entirely and act only on "balances:finalized".

Subscribing

Use the Create Webhook Endpoint API with the BALANCE_CONFIRMED_UPDATES or BALANCE_FINALIZED_UPDATES event type. You can subscribe to one or both by registering a subscription per event type. The endpoint itself is created on the parent organization. Once active, the subscription delivers events for wallet-account addresses across the parent organization and all of its sub-organizations. This covers both addresses Turnkey generated and addresses imported into your Turnkey organization.

Reorg handling

The two-webhook model handles chain reorganizations without any rollback logic on your side. If a confirmed transaction is reorged out of the canonical chain before finality:

1. The original "balances:confirmed" fires when the transaction is first included.
2. The reorg occurs and the transaction is removed from the canonical chain.
3. A new "balances:confirmed" fires when the transaction is included again in the new canonical chain.
4. A "balances:finalized" fires for the canonical inclusion once it reaches finality.

If the transaction never re-enters the canonical chain, no "balances:finalized" event fires for it. Either way, "balances:finalized" is the source of truth for what actually landed onchain. You don’t need to track and roll back state from earlier confirmed events.

Delivery

Balance webhooks use at-least-once processing. If your endpoint is unreachable or a delivery fails on our side, Turnkey will retry. Each payload includes a per-event idempotencyKey, so you can safely deduplicate any duplicate deliveries on your end.

Supported chains

Balance webhooks are currently supported on:

EVM:

• Base - eip155:8453
• Polygon - eip155:137
• Ethereum - eip155:1
• Arbitrum - eip155:42161

EVM testnets:

• Base (Sepolia) - eip155:84532
• Polygon (Amoy) - eip155:80002
• Ethereum (Sepolia) - eip155:11155111
• Arbitrum (Sepolia) - eip155:421614

Solana:

• Solana mainnet - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp (alias: solana:mainnet)
• Solana devnet - solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 (alias: solana:devnet)

Interested in another chain? Reach out to us!

Delivery payload

Each delivery corresponds to a single balance-change event: one address, one operation (deposit or withdraw), and one asset. Because a single transaction can affect multiple addresses or assets, it may produce multiple webhook deliveries — each with its own idempotencyKey.

Example:

{
  "type": "balances:confirmed",
  "organizationId": "95dfcd47-99bb-4433-9126-1524110d68e6",
  "parentOrganizationId": "95dfcd47-99bb-4433-9126-1524110d68e6",
  "msg": {
    "operation": "deposit",
    "caip2": "eip155:8453",
    "txHash": "0x5b6901be92e69781a7ce401dd9a2910e1f49aa77a5bdedcd2a23c8d563d88b24",
    "address": "0x3400e577153101863f39ba41f7fd49bbea011628",
    "idempotencyKey": "d3b8cef0ad7479433783c5707da9ded4fee9b254b4638f44758a2141c49416b7:balances:confirmed",
    "asset": {
      "symbol": "ETH",
      "name": "Ethereum",
      "decimals": 18,
      "caip19": "eip155:8453/slip44:60",
      "amount": "4793760441409"
    },
    "block": {
      "number": 46343814,
      "hash": "0x41a4e8d444e5410f83c1ac35c838c7d8be1e3d6f32a35a04c72096adae74d095",
      "timestamp": "2026-05-22T19:09:35Z"
    }
  }
}

Field	Description
type	"balances:confirmed" for when a balance change is first seen on-chain, or "balances:finalized" when the associated block has the finalization threshold.
organizationId	The organization ID that owns the address.
parentOrganizationId	The parent organization ID.
msg	Object containing the balance change details.
msg.operation	Either "deposit" (incoming) or "withdraw" (outgoing).
msg.caip2	The chain identifier where the event occurred.
msg.txHash	The transaction hash that triggered the balance change.
msg.address	The address whose balance changed.
msg.idempotencyKey	A stable, unique key for this event. Use this to safely deduplicate webhook deliveries.
msg.asset	Asset metadata: symbol, name, decimals, CAIP-19 identifier, and the amount transferred (in the asset’s decimals). Webhooks are emitted only for supported assets.
msg.block	Block number, hash, and timestamp of the block in which the transaction was first seen.

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

Limitations

Balance webhooks fire only for assets in the supported asset list.

Balance webhooks are not supported for private keys.