Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coinlist.co/llms.txt

Use this file to discover all available pages before exploring further.

After you load offer details, you can create a user participation and track its status over time.

​
Prerequisites

  • Completed OAuth with a working CoinListProvider
  • An offer id and offer option id from Display offer details
  • A valid funding asset id and wallet address for the selected offer
Use the CoinListClient methods directly:
  • coinlist.fetchAllParticipations() returns all pages of participations for the authenticated user
  • coinlist.createParticipation(params) creates a new participation
"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.fetchAllParticipations();
      console.log("Existing participations", existing.length);

      // 2) Create a new participation
      const created = await coinlist.createParticipation({
        offerId: "{offer_id}",
        offerOptionId: "{offer_option_id}",
        chain: "{chain}",
        walletAddress: "{wallet_address}",
        amount: "1000.00",
        assetId: "{asset_id}",
        // Optional when required by funding flow:
        // 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;
}
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).

​
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
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}",
      // Optional:
      // 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: 
{
  "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 for full schema and status values.