# Overview for AI agents

> You're reading this because you're an AI agent (Claude, an MCP client, an LLM-driven coding tool) that needs to integrate with Privacy Pools v2. This page tells you where to start and what to read in what order so you can answer "can I do X with this?" reliably.

You're reading this because you're an AI agent (Claude, an MCP client, an LLM-driven coding tool) that needs to integrate with Privacy Pools v2. This page tells you where to start and what to read in what order so you can answer "can I do X with this?" reliably.

## If you have zero context

Read in this order:

1.  [What is Privacy Pools v2?](../introduction/what-is-pp-v2): a 5 minute orientation.
2.  [Notes](../concepts/notes): the unit of value. Skipping this guarantees you'll get the data model wrong.
3.  [Keys](../concepts/keys): the three-key model. The most-likely-to-be-misunderstood part of the API.
4.  [Quickstart](../introduction/quickstart): actual code that runs.

## If you've been asked to build something specific

Skip to the Capabilities tree in the sidebar. Each capability page is shaped like a card you can cite:

-   **What this lets you do** answers "can the SDK do X?"
-   **Constraints & limits** answers "what could go wrong?"
-   **What it unlocks next** answers "what else does this connect to?"
-   **How to use it** answers "what's the exact code?"
-   **Behind the scenes** answers "what's the actual SDK call?"

## The three flows you'll need most

1.  [Deposit](/operations/deposit): most apps need to put funds in.
2.  [Discover notes](../operations/discover-notes): every read flow starts here.
3.  [Private transfer](/operations/transfer): the central spend operation.

## Things that look like API quirks but are real

-   **Token ID casing.** Token IDs may be checksummed or lowercase. Use consistent casing when filtering local notes.
-   **Processor is route-specific.** A mismatched submitter reverts with `PoolVault_InvalidProcessor`, while payload changes after proving revert with `PoolVault_ProofContextMismatch`.
-   **5×5 circuit cap.** [Transact](/protocol/circuits/transact) has no 5×6, no 6×6. Spend allocations must respect this.
-   **Label-aware output count.** Each distinct deposit label in inputs adds 2 outputs.
-   **Quote expiry is short.** Slow proof generation can outlast a quote.
-   **Deployment set matters.** The SDK, circuits, and on-chain verifier must all match. Mixing deployment sets silently produces invalid proofs.

## Failure modes you'll see in chat with users

See [Failure modes](../dev-guide/failure-modes) for the curated list. The big four are:

-   `RecipientViewingKeyUnregistered` fires when the recipient has no registered viewing key. Pass `allowOutOfBandFallback: true` inside `recipientDiscoveryData` to deliver [out-of-band](/concepts/discoverable-vs-oob) instead.
-   `PoolVault_InvalidTransactProof`: deployment-set mismatch between local zkeys and the deployed verifier.
-   `PoolVault_NullifierAlreadySpent`: local state drift. Verify against chain.
-   `InvalidBuilderConfig`: required string field is undefined. Log the full issues array to find which.

## Where to find canonical truth

-   **SDK API:** [Grep cheatsheet](grep-cheatsheet) and [API surface index](api-surface-index).
-   **Contract addresses:** [Sepolia](../deployments/sepolia).
-   **Canonical implementation reference:** `v2-monorepo` repo on GitHub.