@beeperx.ai/sdk

TypeScript SDK for beep.works — the attention layer on Base.

Send paid messages (beeps) to Farcaster users. Look up users, check prices, run targeted campaigns.

Install

npm install @beeperx.ai/sdk

Quick Start — AI Agent

The AgentClient is the simplest way to integrate beeps into your AI agent or bot.

import { AgentClient } from '@beeperx.ai/sdk';

const agent = new AgentClient({
  apiKey: process.env.BEEPER_API_KEY!, // bpk_live_...
});

// Look up a user
const user = await agent.lookup('dwr.eth');
console.log(`@${user.username} — min beep price: $${user.attentionPriceUsd}`);

// Create a payment intent
const intent = await agent.createIntent({
  to: 'dwr.eth',
  amount: '$5',
  message: 'Love your work on Farcaster!',
});
console.log(intent.instruction);
// → "Send 5.50 USDC to 0x1a2b... on Base ($5.00 to @dwr + $0.50 platform fee)"

API Reference — AgentClient

new AgentClient(config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | API key (bpk_live_... or bpk_test_...) | | environment | 'production' \| 'staging' | 'production' | API environment | | baseUrl | string | auto | Custom API base URL | | timeoutMs | number | 30000 | Request timeout | | debug | boolean | false | Enable debug logging |

agent.lookup(identifier)

Look up a user by username, FID, or wallet address.

const user = await agent.lookup('dwr.eth');     // by username
const user = await agent.lookup(3);             // by FID
const user = await agent.lookup('0x1a2b...');   // by wallet

Returns: User

| Field | Type | Description | |-------|------|-------------| | id | string | Internal user ID | | fid | number? | Farcaster ID | | username | string | Username | | displayName | string? | Display name | | pfpUrl | string? | Profile picture URL | | platform | string | Platform (farcaster, twitter) | | walletAddress | string? | Verified wallet address | | attentionPriceUsd | string | Minimum beep price in USD | | followerCount | number? | Follower count |

agent.getPrice(identifier)

Get the attention price for a user.

const price = await agent.getPrice('dwr.eth');
console.log(`$${price.priceUsd} USD`);

agent.createIntent(input)

Create a payment intent. Returns instructions for the user to execute the payment.

const intent = await agent.createIntent({
  to: 'dwr.eth',       // recipient
  amount: '$5',         // amount in USD
  message: 'Hello!',   // required message
  chainId: 8453,        // Base (default)
});

Returns: PaymentIntent with intentId, recipient, amount, instruction, fee breakdown, etc.

Note: A 10% platform fee is added on top. $5 beep → user pays $5.50 USDC total.

agent.estimate(input)

Estimate how many recipients you can reach within a budget.

const estimate = await agent.estimate({
  filters: {
    platform: 'farcaster',
    neynarScoreMin: 0.5,
    minFollowers: 1000,
    countries: ['US'],
  },
  budget: '$100',
});

console.log(`Can reach ${estimate.recipientCount} people`);
console.log(`Total cost: $${estimate.totalCostUsd}`);
console.log(`Budget sufficient: ${estimate.budgetSufficient}`);

agent.preview(input)

Preview sample users matching your filters.

const preview = await agent.preview({
  filters: { neynarScoreMin: 0.7, hasBaseWallet: true },
  limit: 5,
});

preview.users.forEach(u => {
  console.log(`@${u.username} — $${u.priceUsd} — ${u.followerCount} followers`);
});
console.log(`Total matching: ${preview.totalCount}`);

agent.createBulkIntent(input)

Create payment intents for multiple recipients matching filters.

const bulk = await agent.createBulkIntent({
  filters: { signalTokens: ['0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed'] },
  budget: '$50',
  message: 'GM DEGEN community! 🎩',
});

console.log(bulk.summary);
// → "Send to 120 recipients for total 42.50 USDC on Base"

agent.describeFilters()

Get structured filter documentation for LLM system prompts.

const schema = agent.describeFilters();
// Use in your LLM's system prompt for filter-aware conversations

agent.getFilterDocumentation()

Get markdown-formatted filter docs.

const docs = agent.getFilterDocumentation();
// Include in system prompt: `Available filters:\n${docs}`

Filters Reference

Use filters with estimate, preview, and createBulkIntent.

Platform & Activity

| Filter | Type | Description | |--------|------|-------------| | platform | 'all' \| 'farcaster' \| 'twitter' | Target platform | | activeInLastDays | number | Users active within N days |

Reputation & Quality

| Filter | Type | Description | |--------|------|-------------| | neynarScoreMin | number (0-1) | Min Neynar reputation. 0.5+ = quality, 0.8+ = top tier | | neynarScoreMax | number (0-1) | Max Neynar reputation | | quotientScoreMin | number (0-1) | Min Quotient engagement score | | quotientScoreMax | number (0-1) | Max Quotient score | | spamLabel | 'not_spam_only' \| 'spam_only' \| 'all' | Spam classification | | verifiedOnly | boolean | Only wallet-verified users |

Social Graph

| Filter | Type | Description | |--------|------|-------------| | minFollowers | number | Minimum follower count | | maxFollowers | number | Maximum follower count |

Cast Engagement

| Filter | Type | Description | |--------|------|-------------| | castEngagement | { castUrl?: string; castHash?: string; require?: ('like' \| 'recast')[] } | Users who liked and/or recasted a specific cast. If require is omitted, any engagement counts. |

Token Filters

| Filter | Type | Description | |--------|------|-------------| | signalTokens | string[] | Token addresses users set as interests (community affinity) | | tokenHolders | Array<{tokenAddress, chainId, minBalance?}> | Actual onchain token holders | | hasBaseWallet | boolean | Has a Base chain wallet | | hasVerifiedWallet | boolean | Has a verified wallet |

Economics

| Filter | Type | Description | |--------|------|-------------| | maxAttentionPriceUsd | number | Max beep price cap | | minBatteryPercentage | number (0-100) | Min battery (engagement metric) | | hasRechargedInLastDays | number | Checked in within N days | | excludePingedToday | boolean | Skip users already beeped today |

Geography

| Filter | Type | Description | |--------|------|-------------| | countries | string[] | ISO 3166-1 alpha-2 codes (['US', 'KR']) |

Sorting

| Value | Description | |-------|-------------| | attention_price_asc | Cheapest first (maximize reach) | | attention_price_desc | Most expensive first | | neynar_score_desc | Highest reputation first | | followers_desc | Most followers first | | recent_activity | Most recently active | | battery_desc | Highest engagement first | | random | Random order |

Advanced — BeeperClient

For the full deposit → execute → receipt flow:

import { BeeperClient } from '@beeperx.ai/sdk';

const client = new BeeperClient({
  apiKey: process.env.BEEPER_API_KEY!,
});

// 1. Create a draft (local, no API call)
const draft = client.createDraft({
  filter: { and: [
    { field: 'neynarScore', op: 'gte', value: 0.5 },
    { field: 'hasBaseWallet', op: 'eq', value: true },
  ]},
  tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
  chainId: 8453, // Base
  amountPerRecipient: '1000000', // 1 USDC (6 decimals)
  budgetCap: '100000000', // 100 USDC max
});

// 2. Get a quote
const quote = await client.createQuote(draft);

// 3. Deposit tokens to quote.depositAddress
// 4. Confirm deposit
await client.confirmDeposit(quote.id, { txHash: '0x...' });

// 5. Execute
await client.executeSend(quote.id);

// 6. Poll for completion
const receipt = await client.pollUntilCompleteByQuoteId(quote.id);

Error Handling

import { BeeperError, ErrorCodes } from '@beeperx.ai/sdk';

try {
  await agent.lookup('nonexistent');
} catch (err) {
  if (err instanceof BeeperError) {
    console.log(err.code);    // 'NOT_FOUND'
    console.log(err.message); // Human-readable message
    console.log(err.status);  // HTTP status code
  }
}

Retryable errors: RATE_LIMITED, SERVER_ERROR, TIMEOUT. Use exponential backoff.

API Keys

Get your API key at beep.works/sdk.

• bpk_live_... — Production
• bpk_test_... — Sandbox (no real transactions)

Never expose API keys in frontend code. Use server-side only.

Links

• beep.works — Main app
• API Docs — Full API reference
• Discord — Community & support

License

MIT