Ship referrals with your checkout.

Initialize the client

Create the SDK client with your existing viem clients. The wallet client is required for signed transactions; public reads work without it.

// This repository exposes a local SDK module. It is not published to npm.
import { createViralKitClient, ERC20_ABI, encodeCampaignMetadata } from "~~/lib/viralkit";
import { parseUnits, zeroAddress } from "viem";

const viralKit = createViralKitClient({ publicClient, walletClient });

Register a referral identity and create a link

Registration is a wallet-signed, permanent onchain action. Campaign links preserve the same code across apps.

const registrationHash = await viralKit.registerReferralCode("ALICE");
const registrationReceipt = await publicClient.waitForTransactionReceipt({ hash: registrationHash });
if (registrationReceipt.status !== "success") throw new Error("Registration failed");

const referralLink = viralKit.generateCampaignReferralLink(window.location.origin, campaignId, "ALICE");

Create a campaign

Campaign settings are written onchain by the connected merchant. Read token decimals before converting a human-readable price.

const decimals = await publicClient.readContract({
  address: ausdAddress, abi: ERC20_ABI, functionName: "decimals",
});
const hash = await viralKit.createCampaign({
  token: ausdAddress, price: parseUnits("10", decimals),
  commissionBps: 2_000,
  metadata: encodeCampaignMetadata({ name: "Pro plan", description: "Full access" }),
});
const receipt = await publicClient.waitForTransactionReceipt({ hash });
if (receipt.status !== "success") throw new Error("Campaign creation failed");

Read real campaign activity

Onchain aggregates and event logs are scoped to one campaign so each amount uses that campaign’s token and decimals.

const [sales, merchantRevenue, referralEarnings, purchaseEvents] = await Promise.all([
  viralKit.getCampaignSales(campaignId),
  viralKit.getCampaignMerchantRevenue(campaignId),
  viralKit.getCampaignReferralEarnings(campaignId, referrerAddress),
  viralKit.getCampaignPurchaseEvents(campaignId, deploymentBlock),
]);

Resolve and purchase

Resolve the code for display and submit it with the checkout. The SDK checks allowance and balance, requests approval when required, then returns the purchase transaction hash.

const referrer = await viralKit.resolveReferralCode(referralCode);
const referral = referrer === zeroAddress ? "" : referralCode;
const hash = await viralKit.purchaseWithReferral(campaignId, referral);
const receipt = await publicClient.waitForTransactionReceipt({ hash });
if (receipt.status !== "success") throw new Error("Purchase failed");
const hasAccess = await viralKit.hasPurchased(campaignId, buyerAddress);
if (hasAccess) {
  // Your application may now grant its own product access.
}

Verify purchase access using hasPurchased(campaignId, buyerAddress). ViralKit does not deliver a separate digital product.

Network and contracts

ViralKit currently targets Monad Testnet (chain ID 10143). Payments and balances shown in this environment use test assets with no real-world value. The deployed ReferralHub and AUSD token addresses are provided to the app through public environment configuration.

For a campaign link, use /checkout/{campaignId}. Add a referral code as the `ref` query parameter.