> ## Documentation Index
> Fetch the complete documentation index at: https://docs.passage.coinlist.co/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK quickstart

> Get OAuth credentials, install the Passage React SDK, and understand client, server, and API layers.

This guide covers **credentials** and **installing the SDK**. When you are ready to wire sign-in, continue with **[Set up OAuth authentication](/sdk/oauth-authentication)**, then **[Fetch offers](/sdk/fetch-offers)**, then **[Display offer details](/sdk/sale-details)**. Examples use **Next.js App Router** patterns; you can adapt the same pieces to other React frameworks as long as you have a **dedicated backend**.

<Tip>
  Clone the [Partner Demo GitHub repo](https://github.com/coinlist/partner-demo) and follow this tutorial alongside the running example integration. You see it live at [partner.coinlist.dev](https://partner.coinlist.dev/).
</Tip>

## Get OAuth credentials

You need values from Passage before you write code:

* **`client_id`** - public identifier for your app
* **`redirect_uri`** - exact callback URL registered with Passage (must match what you pass in the SDK)
* **`client_secret`** - **server-only**; never expose this to the browser or commit it to frontend bundles

Request access and registration through [Support](/support) or your Passage contact. Store secrets in server environment variables (for example `COINLIST_CLIENT_SECRET`), and use `NEXT_PUBLIC_` only for values that are safe in the client (typically `client_id` and `redirect_uri`).

## Install the SDK

```bash theme={null}
npm install @coinlist-co/react
```

Peer dependencies: `react` and `react-dom` >= 18, and `viem` ^2 (added in v0.9.0 for the on-chain swap flow).

See [Package overview](/sdks) for all import paths (`@coinlist-co/react`, `@coinlist-co/react/server`, `@coinlist-co/react/shared`).

## SDK shape: client, server, and layers

### Browser vs server

* **Browser (React)** - `CoinListClient` runs in the client bundle. It starts and completes the OAuth redirect flow (PKCE + state in `sessionStorage`), calls your `getAccessToken` to hydrate the session, and exposes methods such as `fetchOffers` and `fetchOfferDetails`.
* **Server** - `CoinListServer` runs in route handlers. It exchanges the authorization code for tokens, persists the session (you provide storage), refreshes access tokens, and serves a current access token to the client.

You always combine both: the client drives redirects and UI; the server holds `client_secret` and refresh tokens.

### Abstraction levels (prefer the top)

```mermaid theme={null}
flowchart TB
  components [React components]
  hooks [React hooks]
  core [CoinListClient and CoinListServer]
  components --> hooks
  hooks --> core
```

1. **Highest - React components** (from `@coinlist-co/react`) - UI and behavior together (for example `CoinListSignInCard`, `OffersGrid`). Use these first for the fastest integration.
2. **Mid - React hooks** (from `@coinlist-co/react`) - Stateful behavior you mount in your own layout (`useCompleteOAuth`, `useOffers`, `useOfferDetails`, `useParticipations`, `useRequirements`).
3. **Low - TypeScript clients** (`CoinListClient`, `CoinListServer`) - Imperative APIs with no React. Use for custom UX, non-React apps, or thin wrappers.

**Recommendation:** Start with components, drop down to hooks only when you need custom UI, and use core/server when you are not in React or need full control.

The **HTTP API** ([API reference](/api-reference)) remains the contract underneath the SDK. Reach for it for bespoke HTTP stacks or endpoints the SDK does not wrap yet.

## Next step

<Card title="Set up OAuth authentication" icon="shield-check" href="/sdk/oauth-authentication" horizontal>
  Add `CoinListProvider`, a sign-in surface, callback handling, and server routes.
</Card>

After OAuth, follow **[Fetch offers](/sdk/fetch-offers)** to render `OffersGrid` (or hooks / `fetchOffers` if you customize), then **[Display offer details](/sdk/sale-details)** for a single offer. For funding and participation tracking, see **[Create and track participations](/sdk/participations)** and **[Build the invest flow](/sdk/invest-flow)**, or **[Build the swap flow](/sdk/swap-flow)** for on-chain swap offers. Use the **[API reference](/api-reference)** when you need raw request and response details.