> ## Documentation Index
> Fetch the complete documentation index at: https://turnkey-0e7c1f5b-taylor-webhooks-v2-dream-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Balances
> Learn about Turnkey's balance querying and balance change webhooks.
# Overview
Balance features are currently in **closed beta**. Please reach out to us to request access.
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](/api-reference/queries/get-balances) endpoint returns all non-zero balances for a
given address on a specified chain. You can also call
[List Supported Assets](/api-reference/queries/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](https://github.com/tkhq/sdk/tree/main/examples/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
**EVM testnets:**
* **Base (Sepolia)** - eip155:84532
* **Polygon (Amoy)** - eip155:80002
* **Ethereum (Sepolia)** - eip155:11155111
**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-reference/queries/get-balances) API to check for updates,
you register an endpoint and Turnkey pushes the data to you; an HTTP POST fires when a supported
asset transfer is first confirmed in a block onchain. Webhook payloads deliver balance diffs as soon
as a transaction is confirmed in a block. 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.
Webhook delivery does **not** mean the transaction is finalized. A chain reorganization could
still occur and the transaction may be removed from the canonical chain. Support for finalized
webhook events will be added before this feature exits closed beta.
#### Subscribing
Use the [Create Webhook Endpoint](/api-reference/activities/create-webhook-endpoint) API with the
`BALANCE_CONFIRMED_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.
#### Supported chains
Balance webhooks are currently supported on:
**EVM:**
* **Base** - eip155:8453
* **Polygon** - eip155:137
* **Ethereum** - eip155:1
**EVM testnets:**
* **Base (Sepolia)** - eip155:84532
* **Polygon (Amoy)** - eip155:80002
* **Ethereum (Sepolia)** - eip155:11155111
**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:
```json theme={null}
{
"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](https://github.com/tkhq/sdk/tree/main/examples/with-tx-webhooks) SDK
example for a working integration.
#### Limitations
Balance webhooks fire only for assets in the [supported asset
list](/api-reference/queries/list-supported-assets).
Balance webhooks are not supported for private keys.