# 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, identity verification (KYC & AML), card issuing, payment processing, fiat ramps, 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 (cards, KYC, fiat ramps), 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 (card issuing, KYC submission, 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: payment and ramp flow initiation, card issuing and card-level controls (freeze, set limits, terminate), KYC and AML orchestration (identity submission, screening triggers, status polling), provider-credential flows that require API keys or signing secrets, and webhook processing, event verification, and ledger reconciliation.

```
import { CityPaymentClient, CityKycClient } from "@cityprotocol/core";

const payments = new CityPaymentClient({ apiKey: process.env.CITY_API_KEY });
const kyc = new CityKycClient({ apiKey: process.env.CITY_API_KEY });
```

#### 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.

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

const portfolioClient = new CityPortfolioClient();
// Safe for the frontend — no credentials required.
// Queries indexed subgraph data for vault lists, TVL charts, and transaction history.
```

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                                        |
| ----------------------------------------- | ------------------------------------------------------ |
| Backend services (payments, cards, KYC)   | `bun add @cityprotocol/core`                           |
| 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` |


---

# Agent Instructions: 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:

```
GET https://city-protocol.gitbook.io/docs/software-development-kit/overview/get-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.