> For the complete documentation index, see [llms.txt](https://city-protocol.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://city-protocol.gitbook.io/docs/neofinance-as-a-service/wallet.md).

# Wallet

### Architecture Overview

City Protocol's wallet layer is the identity and account-access foundation of every product built on the platform. It is designed to authenticate users, provision or connect wallets, and verify wallet-linked sessions across client and server boundaries using Privy and the City SDK. 

This module handles the full lifecycle from login to backend-verified identity, ensuring that every downstream product feature, including vault interactions, access-gated flows, and on-chain operations, are anchored to a cryptographically verified wallet session.

> Wallet integration uses **Privy** for client-side authentication and embedded wallet provisioning, and **@cityprotocol/core** for server-side identity verification. The architecture is stateless on the backend and framework-agnostic on the client.

***

### Key Components

<table><thead><tr><th width="124.109375">Component</th><th>Description</th></tr></thead><tbody><tr><td><strong>Privy Provider</strong></td><td>Wraps the React application tree and manages authentication state, login methods, and embedded wallet creation policy.</td></tr><tr><td><strong>Identity Token</strong></td><td>A signed token issued by Privy after authentication. It encodes the user's session and linked wallet, and is the sole credential your backend should trust.</td></tr><tr><td><strong>City SDK Verifier</strong></td><td>A server-side utility (<code>verifyPrivyWallet</code>) exposed by <code>@cityprotocol/core</code> that validates the identity token, extracts the user profile, and returns the associated wallet address.</td></tr><tr><td><strong>Wallet Gate</strong></td><td>A client-side component pattern that conditionally renders UI based on authentication state, and attaches the identity token to outbound API calls.</td></tr></tbody></table>