React SDK

1npm install coal-react

1// app/layout.tsx
2import { CoalProvider } from 'coal-react';
3
4export default function RootLayout({ children }) {
5  return (
6    <CoalProvider merchantId="your-coal-merchant-id">
7      {children}
8    </CoalProvider>
9  );
10}

1import { CoalBuyButton } from 'coal-react';
2
3<CoalBuyButton
4  createSession={async () => {
5    const res = await fetch('/api/create-checkout', { method: 'POST' });
6    return res.json(); // must return { url } or { sessionId }
7  }}
8>
9  Buy for $9.99
10</CoalBuyButton>

1// app/.well-known/agent-card.json/route.ts
2import { createAgentCardRoute } from 'coal-react/next';
3export const GET = createAgentCardRoute({ merchantId: 'your-merchant-id' });

1<CoalCheckoutButton
2  checkoutUrl={url}
3  onBeforeRedirect={() => analytics.track('checkout')}
4/>

1<CoalBuyButton
2  createSession={async () => {
3    const res = await fetch('/api/checkout', { method: 'POST' });
4    return res.json();
5  }}
6  onError={(err) => toast.error(err.message)}
7>
8  Buy Now — $29.99
9</CoalBuyButton>

1<CoalProducts layout="grid" columns={2} />

1<CoalProduct id="product-id" />

1<CoalAgentPublisher
2  products={[
3    { externalId: 'sku-1', name: 'Pro Plan', price: 29.99, description: '...' },
4    { externalId: 'sku-2', name: 'Enterprise', price: 99, image: 'https://...' },
5  ]}
6  showStatus
7  onPublish={(result) => console.log('Indexed:', result.zeroG.storageUri)}
8/>

1<CoalSchemaOrg />

1const {
2  receipt,        // CoalReceipt object
3  loading,        // true while polling
4  error,          // string | null
5  fullyVerified,  // true when all 3 steps are green
6  verifiedSteps,  // 0..3
7} = useCoalReceipt(sessionId, {
8  pollIntervalMs: 2000, // default
9  timeoutMs: 60000,     // default
10});

1const { checkoutUrl, redirectToCheckout, openCheckout } = useCoalCheckout({
2  sessionId: 'abc123',
3});

1import { publishCoalCatalog, CoalPublishError } from 'coal-react/server';
2
3try {
4  const result = await publishCoalCatalog({
5    merchantId: 'your-merchant-id',
6    apiKey: process.env.COAL_API_KEY!,
7    products: [
8      { externalId: 'sku-1', name: 'Pro Plan', price: 29.99 },
9    ],
10    mode: 'upsert',
11  });
12
13  console.log(result.zeroG.storageUri); // "0g://log/0x..."
14} catch (err) {
15  if (err instanceof CoalPublishError) {
16    console.error(err.status, err.code, err.message);
17    // 401 UNAUTHORIZED, 429 RATE_LIMITED, 400 VALIDATION_ERROR
18  }
19}

1// app/api/coal/publish-catalog/route.ts
2import { publishCoalCatalog } from 'coal-react/server';
3
4export async function POST(request: Request) {
5  // ⚠️ Add your own auth here (session check, CSRF token, etc.)
6  const body = await request.json();
7
8  const result = await publishCoalCatalog({
9    merchantId: process.env.NEXT_PUBLIC_COAL_MERCHANT_ID!,
10    apiKey: process.env.COAL_API_KEY!,
11    products: body.products,
12    mode: body.mode ?? 'upsert',
13  });
14
15  return Response.json(result);
16}

1// app/.well-known/agent-card.json/route.ts
2import { createAgentCardRoute } from 'coal-react/next';
3
4export const GET = createAgentCardRoute({
5  merchantId: 'your-merchant-id',
6  name: 'My Store',          // optional
7  description: 'We sell...',  // optional
8  cacheMaxAge: 300,           // Cache-Control max-age in seconds (default: 300)
9});

1// app/llms.txt/route.ts
2import { createLlmsTxtRoute } from 'coal-react/next';
3
4export const GET = createLlmsTxtRoute({
5  merchantId: 'your-merchant-id',
6  title: 'My Store',
7  summary: 'We sell digital goods payable in USDC on Base via Coal.',
8});

1// app/.well-known/x402.json/route.ts
2import { createX402ManifestRoute } from 'coal-react/next';
3
4export const GET = createX402ManifestRoute({
5  merchantId: 'your-merchant-id',
6});

1// Client components
2import type {
3  CoalCheckoutButtonProps,
4  CoalBuyButtonProps,
5  CoalProductsProps,
6  CoalAgentPublisherProps,
7  CoalSchemaOrgProps,
8  CoalProductSummary,
9  CoalPaywallSummary,
10  CoalMerchantProfile,
11  CoalReceipt,
12  UseCoalCheckoutOptions,
13  UseCoalCheckoutReturn,
14  UseCoalReceiptOptions,
15  UseCoalReceiptResult,
16} from 'coal-react';
17
18// Server helper
19import type {
20  CoalCatalogProduct,
21  PublishCoalCatalogOptions,
22  PublishCoalCatalogResult,
23  CoalPublishError,
24} from 'coal-react/server';
25
26// Next.js route helpers
27import type {
28  AgentCardRouteOptions,
29  LlmsTxtRouteOptions,
30  X402ManifestRouteOptions,
31} from 'coal-react/next';