@pepay-streams/sdk

TypeScript SDK for interacting with the Pepay Streams protocol - a production-grade EVM token distribution platform built on EIP-2535 Diamond architecture.

Features

• Token Distribution: Create instant airdrops, vested airdrops, token locks, and vesting streams
• Staking Pools: Create and manage fixed-duration staking pools with APY-based rewards
• P2P Marketplace: Trade unvested positions through INSTANT, VESTED, and TRADABLE orders
• Automation: Enable keeper-powered auto-withdraw and auto-release
• Meta-Transactions: Support for gasless claims via EIP-712 signatures
• Type-Safe: Full TypeScript support with comprehensive types

Installation

npm install @pepay-streams/sdk viem
# or
pnpm add @pepay-streams/sdk viem
# or
yarn add @pepay-streams/sdk viem

Quick Start

Read-Only Client

import { PepayStreamsClient } from '@pepay-streams/sdk';

const client = new PepayStreamsClient({
  rpcUrl: 'https://eth.llamarpc.com',
  diamondAddress: '0x...',
  chainId: 1,
  apiBaseUrl: 'https://api.pepaystreams.com', // Optional
});

// Query campaigns
const campaign = await client.campaigns.getCampaign(1n);
console.log('Campaign:', campaign.name);

// Check claimable amount
const due = await client.claims.getDueAmount(1n, '0x...');
console.log('Due amount:', due);

Client with Signer (for transactions)

import { PepayStreamsClient } from '@pepay-streams/sdk';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { mainnet } from 'viem/chains';

// From private key (Node.js/scripts)
const client = PepayStreamsClient.fromPrivateKey({
  rpcUrl: 'https://eth.llamarpc.com',
  diamondAddress: '0x...',
  chainId: 1,
  privateKey: '0x...',
});

// Or attach a wallet client
const walletClient = createWalletClient({
  chain: mainnet,
  transport: http(),
  account: privateKeyToAccount('0x...'),
});

const clientWithSigner = new PepayStreamsClient({
  rpcUrl: 'https://eth.llamarpc.com',
  diamondAddress: '0x...',
  chainId: 1,
}).withSigner(walletClient);

Browser Wallet

import { PepayStreamsClient } from '@pepay-streams/sdk';

// Connect to browser wallet (MetaMask, etc.)
const client = await PepayStreamsClient.fromBrowserWallet({
  diamondAddress: '0x...',
  chainId: 1,
});

Campaign Operations

Create an Instant Airdrop

import { parseEther } from 'viem';

const result = await client.campaigns.createInstantAirdrop({
  token: '0x...', // Token address
  name: 'Community Airdrop',
  recipients: [
    { address: '0x...', amount: parseEther('100') },
    { address: '0x...', amount: parseEther('50') },
  ],
});

await result.wait();
console.log('Created! Tx:', result.hash);

Create a Vested Airdrop

const result = await client.campaigns.createVestedAirdrop({
  token: '0x...',
  name: 'Team Vesting',
  recipients: [
    { address: '0x...', amount: parseEther('10000') },
  ],
  startTime: Math.floor(Date.now() / 1000), // Start now
  duration: 365 * 24 * 60 * 60, // 1 year
  cliffDuration: 90 * 24 * 60 * 60, // 3 month cliff
  steps: 12, // Monthly releases
});

Create a Token Lock

const result = await client.campaigns.createLock({
  token: '0x...',
  name: 'Liquidity Lock',
  recipient: '0x...',
  amount: parseEther('1000000'),
  unlockTime: Math.floor(Date.now() / 1000) + 180 * 24 * 60 * 60, // 6 months
});

Create a Vesting Stream (Payment)

const result = await client.campaigns.createVesting({
  token: '0x...',
  name: 'Salary Stream',
  recipient: '0x...',
  amount: parseEther('120000'),
  startTime: Math.floor(Date.now() / 1000),
  duration: 365 * 24 * 60 * 60, // 1 year
  steps: 12, // Monthly
  enableAutoWithdraw: true,
  autoWithdrawFrequency: 30 * 24 * 60 * 60, // Monthly auto-claim
});

Claiming

Claim Tokens

// Single claim
const result = await client.claims.claim({ campaignId: 1n });
await result.wait();

// Batch claim from multiple campaigns
const result = await client.claims.claimBatch({
  campaignIds: [1n, 2n, 3n],
});

// Release a lock
const result = await client.claims.releaseLock(campaignId);

Check Claimable Amount

const due = await client.claims.getDueAmount(campaignId, recipientAddress);
console.log('Claimable:', formatEther(due));

const status = await client.claims.getRecipientStatus(campaignId, recipientAddress);
console.log('Allocated:', status.allocated);
console.log('Claimed:', status.claimed);
console.log('Due:', status.due);

Meta-Transaction (Gasless) Claims

// Recipient signs off-chain
const { signature, nonce, deadline } = await client.claims.signClaimMessage(
  campaignId,
  Math.floor(Date.now() / 1000) + 3600 // 1 hour deadline
);

// Relayer submits the transaction
const result = await relayerClient.claims.claimWithSig({
  campaignId,
  signature,
  deadline,
  signer: recipientAddress,
});

Staking

Create a Staking Pool

const result = await client.staking.createPool({
  stakeToken: '0x...', // Token users stake
  rewardToken: '0x...', // Token users earn
  rewardBudget: parseEther('100000'), // Total rewards
  duration: 30 * 24 * 60 * 60, // 30 days
  minStake: parseEther('100'),
  maxStake: parseEther('10000'),
});

Stake Tokens

// Approve first
await client.approve(stakeToken, amount);

// Then stake
const result = await client.staking.stake(poolId, amount);
await result.wait();

Claim Rewards

// Check pending rewards
const pending = await client.staking.getPendingRewards(poolId, address);

// Claim
await client.staking.claimRewards(poolId);

// Or unstake (automatically claims rewards)
await client.staking.unstake(poolId, amount);

Marketplace

Create an Order

import { zeroAddress } from 'viem';

// INSTANT order - immediate delivery
await client.marketplace.createInstantOrder({
  sellToken: '0x...',
  sellAmount: parseEther('1000'),
  payToken: zeroAddress, // Native ETH
  pricePerToken: parseEther('0.001'),
  expiryTTL: 7 * 24 * 60 * 60, // 7 days
});

// TRADABLE order - list unvested campaign position
await client.marketplace.createTradableOrder({
  campaignId: 10n,
  pricePerToken: parseEther('0.05'),
  payToken: zeroAddress,
  expiryTTL: 30 * 24 * 60 * 60,
});

Fill an Order

// Get quote
const quote = await client.marketplace.getQuote(orderId);
console.log('Total price:', quote.totalPrice);

// Fill with native payment
await client.marketplace.fillOrder(orderId, {
  value: quote.totalPrice,
});

// Or with ERC20 (approve first)
await client.approve(payToken, quote.totalPrice);
await client.marketplace.fillOrder(orderId);

Cancel an Order

await client.marketplace.cancelOrder(orderId);

Automation

Enable Auto-Withdraw

await client.automation.enableAutoWithdraw({
  campaignId: 1n,
  frequency: 7 * 24 * 60 * 60, // Weekly
  tipAmount: parseEther('0.1'), // Keeper tip
});

Enable Auto-Release for Locks

await client.automation.enableAutoRelease({
  campaignId: 5n,
  tipAmount: parseEther('0.05'),
});

Check Automation Status

const status = await client.automation.getAutoWithdrawStatus(campaignId);
console.log('Enabled:', status.enabled);
console.log('Next run:', new Date(status.nextRun * 1000));
console.log('Tip balance:', status.tipBalance);

API Client (Indexed Data)

const client = new PepayStreamsClient({
  rpcUrl: '...',
  diamondAddress: '0x...',
  chainId: 1,
  apiBaseUrl: 'https://api.pepaystreams.com',
});

// Get campaigns with filtering
const campaigns = await client.api.getCampaigns({
  kind: 'vested_airdrop',
  status: 'active',
  page: 1,
  pageSize: 20,
});

// Get wallet activity
const activity = await client.api.getWalletActivity(address);

// Get marketplace orders
const orders = await client.api.getOrders({
  orderType: 'tradable',
  status: 'open',
});

React Integration

See @pepay-streams/sdk/react for React-specific helpers:

import { queryKeys, formatters } from '@pepay-streams/sdk/react';

// Use with react-query
const { data } = useQuery({
  queryKey: queryKeys.campaign(campaignId),
  queryFn: () => client.campaigns.getCampaign(campaignId),
});

// Format amounts
formatters.formatTokenAmount(amount, 18); // "1,234.56"
formatters.shortenAddress(address); // "0x1234...5678"

Module Exports

// Main client
import { PepayStreamsClient } from '@pepay-streams/sdk';

// Individual modules
import { CampaignsModule } from '@pepay-streams/sdk/campaigns';
import { ClaimsModule } from '@pepay-streams/sdk/claims';
import { StakingModule } from '@pepay-streams/sdk/staking';
import { MarketplaceModule } from '@pepay-streams/sdk/marketplace';
import { AutomationModule } from '@pepay-streams/sdk/automation';
import { ApiClient } from '@pepay-streams/sdk/api';

// React helpers
import { queryKeys, formatters } from '@pepay-streams/sdk/react';

Types

All types are fully exported:

import type {
  PepayStreamsConfig,
  CampaignInfo,
  PoolInfo,
  OrderInfo,
  RecipientStatus,
  // ... and more
} from '@pepay-streams/sdk';

Supported Chains

• Ethereum Mainnet (1)
• BNB Smart Chain (56)
• Local Anvil (31337)

License

MIT