> 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/software-development-kit/overview/get-started.md).

# Get Started

{% hint style="info" icon="desktop" %}
The `@cityprotocol/core` package provides a unified TypeScript SDK for interacting with City Protocol's smart contracts. It wraps complex multi-step transactions (like ERC-20 approvals and asynchronous cooldowns) into simple asynchronous functions.
{% endhint %}

### Recommended Starting Point

For most teams the integration path is the same:

1. Install `@cityprotocol/core` in your backend or integration service.
2. Add frontend-only packages separately when a user-facing flow requires them.
3. Keep provider credentials and sensitive logic on the server.

***

### Core Package

```bash
bun add @cityprotocol/core
```

`@cityprotocol/core` is the primary package for every City integration. It contains builder-facing clients for wallet operations, token swaps, lending markets, yield vaults, and indexed portfolio data. 

All multi-step flows, such as provider handshakes, approval chains, and webhook verification, are wrapped into simple asynchronous functions.

***

### With Viem (On-Chain Actions)

If your integration includes on-chain wallet actions — vault deposits, token transfers, or lending operations through `CityClient` — install `viem` as a peer dependency:

```bash
bun add @cityprotocol/core viem
```

`CityClient` expects a Viem wallet client with an active account. If your product only uses off-chain City services, you do not need `viem`.

```
import { CityClient } from "@cityprotocol/core";

const client = new CityClient(walletClient);
```

***

### With Privy (React)

If you build a React-based wallet connection and login flow using Privy, install the Privy React auth package alongside core:

bash

```bash
bun add @cityprotocol/core @privy-io/react-auth
```

Privy handles embedded wallet creation, social login, and session management on the frontend. Your backend should still hold provider credentials and call `@cityprotocol/core` directly for any privileged operation (e.g., webhook verification).

***

### Setup by Runtime

#### Backend

Install `@cityprotocol/core` on the backend first. The server is the correct home for any flow that touches provider credentials or sensitive user data.

Backend-owned responsibilities include: provider-credential flows that require API keys or signing secrets, and webhook processing, event verification, and ledger reconciliation.

#### Frontend

Use frontend packages only when the UX requires direct user interaction — wallet connection prompts, hosted identity-verification launch flows, or real-time balance displays. All secrets and privileged calls should remain server-side; the frontend communicates with your backend, which in turn calls City.

For live on-chain reads (share balances, cooldown states, withdrawable amounts), pair `CityPortfolioClient` with `CityClient` on the frontend. For any write operation that involves provider keys or user PII, route through your backend.

***

### Create A Client

The `CityClient` is your primary interface for all on-chain vault interactions. It expects a Viem wallet client with an active account.

```tsx
import { CityClient } from "@cityprotocol/core";
const client = new CityClient(walletClient);
```

***

### Quick Reference

| What you're building                      | Install command                                        |
| ----------------------------------------- | ------------------------------------------------------ |
| On-chain actions (vaults, swaps, lending) | `bun add @cityprotocol/core viem`                      |
| React wallet login (Privy)                | `bun add @cityprotocol/core @privy-io/react-auth`      |
| Full-stack with on-chain + Privy          | `bun add @cityprotocol/core viem @privy-io/react-auth` |