> For the complete documentation index, see [llms.txt](https://docs.zama.org/protocol/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zama.org/protocol/sdk/api-references/react/query-keys.md).

# Query keys

The `zamaQueryKeys` object is a factory for React Query cache keys. Use it to invalidate, prefetch, or remove cached data manually.

Mutations auto-invalidate related caches, so you only need `zamaQueryKeys` for advanced cache control.

## Import

```ts
import { zamaQueryKeys } from "@zama-fhe/sdk/query";
```

## Usage

```tsx
import { useQueryClient } from "@tanstack/react-query";
import { zamaQueryKeys } from "@zama-fhe/sdk/query";

const queryClient = useQueryClient();

// Invalidate all balances
queryClient.invalidateQueries({ queryKey: zamaQueryKeys.confidentialBalance.all });

// Invalidate one token's balances
queryClient.invalidateQueries({ queryKey: zamaQueryKeys.confidentialBalance.token("0xToken") });

// Invalidate a specific owner's balance
queryClient.invalidateQueries({
  queryKey: zamaQueryKeys.confidentialBalance.owner("0xToken", "0xOwner"),
});
```

## Key factories

### `zamaQueryKeys.confidentialBalance`

Single-token decrypted balance.

| Key                   | Scope                             |
| --------------------- | --------------------------------- |
| `.all`                | All decrypted balances            |
| `.token(addr)`        | All balances for one token        |
| `.owner(addr, owner)` | One owner's balance for one token |

### `zamaQueryKeys.confidentialBalances`

Multi-token batch balances.

| Key                     | Scope                                     |
| ----------------------- | ----------------------------------------- |
| `.all`                  | All batch balance queries                 |
| `.tokens(addrs, owner)` | Batch query for specific tokens and owner |

### `zamaQueryKeys.hasPermit`

Permit coverage status.

| Key    | Scope                   |
| ------ | ----------------------- |
| `.all` | All `hasPermit` queries |

### `zamaQueryKeys.underlyingAllowance`

ERC-20 allowance of the underlying token for the wrapper.

| Key                   | Scope                                      |
| --------------------- | ------------------------------------------ |
| `.all`                | All allowance queries                      |
| `.token(addr)`        | Allowances for one token                   |
| `.scope(addr, owner)` | Specific owner's allowance for the wrapper |

### `zamaQueryKeys.wrappersRegistry`

On-chain wrappers registry queries.

| Key                                                         | Scope                                 |
| ----------------------------------------------------------- | ------------------------------------- |
| `.all`                                                      | All registry queries                  |
| `.chainId()`                                                | Chain ID resolution                   |
| `.tokenPairs(registryAddr)`                                 | All pairs for a registry              |
| `.tokenPairsLength(registryAddr)`                           | Pair count                            |
| `.tokenPairsSlice(registryAddr, from, to)`                  | Index-based slice                     |
| `.tokenPair(registryAddr, index)`                           | Single pair by index                  |
| `.confidentialTokenAddress(registryAddr, tokenAddr)`        | Forward lookup (plain → confidential) |
| `.tokenAddress(registryAddr, confidentialAddr)`             | Reverse lookup (confidential → plain) |
| `.isConfidentialTokenValid(registryAddr, confidentialAddr)` | Validity check                        |
| `.listPairs(registryAddr, page, pageSize, metadata)`        | Paginated listing                     |

### `zamaQueryKeys.decryption`

Cached decrypted values. Populated by [`useDecryptValues`](/protocol/sdk/api-references/react/usedecryptvalues.md).

```ts
import { zamaQueryKeys } from "@zama-fhe/sdk/query";
```

| Key                                                   | Scope                                          |
| ----------------------------------------------------- | ---------------------------------------------- |
| `.encryptedValue(encryptedValue, contractAddress?)`   | Single clear value by encrypted value          |
| `.encryptedInputs(encryptedInputs[], walletAccount?)` | Multiple clear values by encrypted-input array |

## Common patterns

### Invalidate after an external transaction

```tsx
// After a transfer made outside the SDK
queryClient.invalidateQueries({ queryKey: zamaQueryKeys.confidentialBalance.token("0xToken") });
```

### Prefetch balances on hover

```tsx
queryClient.prefetchQuery({
  queryKey: zamaQueryKeys.confidentialBalance.owner("0xToken", "0xOwner"),
  queryFn: () => fetchBalance("0xToken", "0xOwner"),
});
```

### Clear all cached data on disconnect

```tsx
queryClient.removeQueries({ queryKey: zamaQueryKeys.confidentialBalance.all });
```

## Related

* [ZamaProvider](/protocol/sdk/api-references/react/zamaprovider.md) — provider setup and hook overview
* [`useConfidentialBalance`](/protocol/sdk/api-references/react/useconfidentialbalance.md) — the hook whose cache these keys control


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zama.org/protocol/sdk/api-references/react/query-keys.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.