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

# Create and track participations

> List participations with useParticipations or CoinListClient, and create a participation for an offer option.

After you load [offer details](/sdk/sale-details), you can create a user participation and track its status over time. This page covers the SDK surface (listing, fetching, creating). For the end-to-end UX flow - wallet connect, on-chain approval, then `createParticipation` - see [Build the invest flow](/sdk/invest-flow).

## Prerequisites

* Completed [OAuth](/sdk/oauth-authentication) with a working `CoinListProvider`
* An offer id and offer option id from [Display offer details](/sdk/sale-details)
* A valid funding asset id and wallet address for the selected offer
* The hash of the ERC-20 approval transaction for the funding amount (see [Build the invest flow](/sdk/invest-flow))

## Recommended: useParticipations hook + CoinListClient

For the reactive case, use the **`useParticipations(offerId?)`** hook - it loads all participations for the authenticated user with a `LOADING / CONTENT / ERROR` state machine, optionally scoped to one offer. For imperative reads or writes, drop down to `CoinListClient`:

* `coinlist.tokenSale.fetchParticipations(offerId?)` returns all pages of participations for the authenticated user
* `coinlist.tokenSale.createParticipation(params)` creates a new participation

```tsx theme={null}
"use client";

import { useCoinList } from "@coinlist-co/react";
import { useEffect } from "react";

export function ParticipationExample() {
  const { coinlist, isReady } = useCoinList();

  useEffect(() => {
    if (!isReady) return;

    const run = async () => {
      // 1) List existing participations
      const existing = await coinlist.tokenSale.fetchParticipations();
      console.log("Existing participations", existing.length);

      // 2) Create a new participation
      const created = await coinlist.tokenSale.createParticipation({
        offerId: "{offer_id}",
        offerOptionId: "{offer_option_id}",
        chain: "{chain}",
        walletAddress: "{wallet_address}",
        amount: "1000.00",
        assetId: "{asset_id}",
        // Required: hash of the ERC-20 approval transaction you submit first
        approvalTransactionHash: "{approval_transaction_hash}",
      });

      console.log("Created participation", created.id, created.status);
    };

    void run().catch((error) => {
      console.error("Participation flow failed", error);
    });
  }, [coinlist, isReady]);

  return null;
}
```

<Note>
  `createParticipation` accepts camelCase keys in the SDK (`offerId`, `offerOptionId`, `walletAddress`, `assetId`). The SDK maps these to the API request fields defined in OpenAPI (`offer_id`, `offer_option_id`, `wallet_address`, `asset_id`).
</Note>

## REST parity: Participations endpoints

Use REST directly when you are not using the SDK client.

* `GET /v1/participations` lists participations for the authenticated partner and user
* `POST /v1/participations` creates a participation

```ts theme={null}
export async function createParticipation(accessToken: string) {
  const response = await fetch("https://api.coinlist.co/v1/participations", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      offer_id: "{offer_id}",
      offer_option_id: "{offer_option_id}",
      chain: "{chain}",
      wallet_address: "{wallet_address}",
      amount: "1000.00",
      asset_id: "{asset_id}",
      // Required: hash of the ERC-20 approval transaction you submit first
      approval_transaction_hash: "{approval_transaction_hash}",
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message ?? "Failed to create participation");
  }

  return response.json();
}
```

Example response shape:

```json theme={null}
{
  "object": "participation",
  "id": "{participation_id}",
  "offer_id": "{offer_id}",
  "offer_option_id": "{offer_option_id}",
  "status": "pending",
  "amount": "1000.00",
  "amount_string": "1,000.00",
  "chain": "{chain}",
  "asset": {
    "id": "{asset_id}",
    "code": "USDC",
    "name": "USD Coin",
    "fractional_digits": 6
  },
  "wallet_address": "{wallet_address}"
}
```

See the [API reference](/api-reference) for full schema and status values.