Skip to main content
This guide covers credentials and installing the SDK. When you are ready to wire sign-in, continue with Set up OAuth authentication, then Fetch offers, then Display offer 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.
Clone the Partner Demo GitHub repo and follow this tutorial alongside the running example integration. You see it live at partner.coinlist.dev.

​
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 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

npm install @coinlist-co/react
Peer dependencies: react and react-dom >= 18. See Package overview for all import paths (@coinlist-co/react, client/components, server, …).

​
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)

  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) remains the contract underneath the SDK. Reach for it for bespoke HTTP stacks or endpoints the SDK does not wrap yet.

​
Next step

Set up OAuth authentication

Add CoinListProvider, a sign-in surface, callback handling, and server routes.
After OAuth, follow Fetch offers to render OffersGrid (or hooks / fetchOffers if you customize), then Display offer details for a single offer. For funding, participation tracking, and errors, see Recipes. Use the API reference when you need raw request and response details.