Display offer details

Fetch full offer details - pricing options, legal terms, milestones, the tokens the offer settles in, and more - for a single offer the user can access.

OfferDetail.type tells you which checkout the offer needs: 'coinlist::token_sale', 'superstate::swap', 'ondo::swap', or 'centrifuge::vault'. Switch on it exhaustively, or hand the offer to CheckoutContainer and let the SDK dispatch. v0.13.0 added 'centrifuge::vault', so an exhaustive switch written for an earlier version needs a new case - see the changelog.

Prerequisites

Completed OAuth and a working PassageProvider
An offer id from Fetch offers (for example offer.id from OffersGridContainer onOfferClick)

Recommended: useOfferDetails

The hook mirrors the SDK client method passage.offers.get: it waits until the provider is ready, then loads details and exposes offerDetailsState:

LOADING - provider not ready or request in flight. With enabled: false and no data, the hook also stays LOADING: it has no DISABLED state.
ERROR - reason is not-authenticated when no user is signed in (NotAuthenticatedError), and generic-error for any other failure
CONTENT - offerDetail is the OfferDetail

Pass data with an OfferDetail your server fetched with passage.offers.get(id) on PassageServer, and the hook uses it as-is and sends no request. The hook has no refetch(). When the user picks an offer from the grid, keep that offer in React state and pass offer.id - TypeScript then matches the branded id type the hook expects.

"use client";

import { useState } from "react";
import { OffersGridContainer, useOfferDetails } from "@passage-cl/react";
import type { Offer } from "@passage-cl/react/universal";

function OfferDetailPanel({ offer }: { offer: Offer }) {
  const { offerDetailsState } = useOfferDetails(offer.id);

  if (offerDetailsState.type === "LOADING") return <p>Loading details…</p>;
  if (offerDetailsState.type === "ERROR") return <p>Unable to load this offer.</p>;

  const detail = offerDetailsState.offerDetail;
  return (
    <section>
      <h1>{detail.name}</h1>
      {/* Render options, terms, milestones from detail - see API reference for fields */}
    </section>
  );
}

export function OfferBrowseAndDetail() {
  const [selected, setSelected] = useState<Offer | null>(null);

  return (
    <>
      <OffersGridContainer onOfferClick={(offer) => setSelected(offer)} />
      {selected ? <OfferDetailPanel offer={selected} /> : null}
    </>
  );
}

REST: GET /v1/offers/

Use the API directly when you are not in React or you need a one-off server fetch with a token you already hold.

Example: fetch with Bearer token

// lib/coinlist-api.ts
export async function getOfferDetails(offerId: string, accessToken: string) {
  const res = await fetch(
    `https://api.coinlist.co/v1/offers/${encodeURIComponent(offerId)}`,
    {
      headers: { Authorization: `Bearer ${accessToken}` },
    },
  );

  if (!res.ok) {
    const error = await res.json();
    throw new Error(error.message ?? "Failed to fetch offer");
  }

  return res.json();
}

See the API reference for the exact response schema.

Example response shape (values are illustrative - always rely on the live API and legal URLs from Passage):

{
  "object": "offer_details",
  "id": "{offer_id}",
  "type": "coinlist::token_sale",
  "slug": "example-offer",
  "name": "Example Token Sale",
  "tagline": "An example token sale",
  "starts_at": "2026-01-01T00:00:00.000000Z",
  "ends_at": "2026-01-31T00:00:00.000000Z",
  "options": [
    {
      "id": "{option_id}",
      "slug": "standard",
      "price_usd": "0.10",
      "floor_price_usd": "0.08",
      "bid_increment": null,
      "minimum_purchase_usd": "100",
      "total_token_supply": 1000000,
      "sale_agreement_url": "https://coinlist.co/agreements/example"
    }
  ],
  "funding_contracts": [
    { "chain": "ethereum_mainnet", "address": "0x0000000000000000000000000000000000000000" }
  ],
  "terms": [
    { "key": "Vesting", "value": "12 months linear" },
    { "key": "Lockup", "value": "6 months cliff" }
  ],
  "milestones": [
    { "name": "Registration", "schedule": "Jan 1", "status": "completed" },
    { "name": "Sale Open", "schedule": "Jan 15", "status": "active" },
    { "name": "Distribution", "schedule": "Feb 1", "status": "upcoming" }
  ],
  "faqs": [],
  "links": []
}

Display the full terms and link to the sale agreement URL as provided - do not summarize or paraphrase legal terms.

Lower-level client

passage.offers.get in React

Equivalent to the hook, without the built-in state machine. Pass the same offer.id you get from OffersGridContainer:

"use client";

import { usePassage } from "@passage-cl/react";
import type { Offer, OfferDetail } from "@passage-cl/react/universal";
import { useEffect, useState } from "react";

export function OfferDetailManual({ offer }: { offer: Offer }) {
  const { passage, isReady } = usePassage();
  const [detail, setDetail] = useState<OfferDetail | null>(null);

  useEffect(() => {
    if (!isReady) return;
    void passage.offers
      .get(offer.id)
      .then(setDetail)
      .catch(() => setDetail(null));
  }, [passage, isReady, offer.id]);

  if (!isReady) return <p>Loading…</p>;
  return <pre>{JSON.stringify(detail, null, 2)}</pre>;
}

Prefer useOfferDetails unless you need custom control flow.

Next step

Requirements

Show the user what they must satisfy before they can participate.

Get started

Offers and requirements

Flows

Reference

Prerequisites

Recommended: useOfferDetails

REST: GET /v1/offers/

Lower-level client

Next step

Requirements

​Prerequisites

​Recommended: useOfferDetails

​REST: GET /v1/offers/

​Lower-level client

​Next step

Requirements

Prerequisites

Recommended: useOfferDetails

REST: GET /v1/offers/

Lower-level client

Next step