SDK Reference

Complete reference for the @pot/sdk TypeScript/JavaScript SDK.

Installation

npm install @pot/sdk

POT Class

The main class for interacting with the POT platform.

Constructor

new POT(config: POTConfig)

Parameter	Type	Required	Description
`apiKey`	string	Yes	Your POT API key (starts with `pot_sk_`)
`baseUrl`	string	No	Custom API URL (default: `https://pot.dev`)
`timeout`	number	No	Request timeout in ms (default: 30000)

import { POT } from '@pot/sdk';

const pot = new POT({
  apiKey: 'pot_sk_xxx',
  timeout: 60000
});

register(options?)

pot.register(options?: RegisterOptions): Promise<RegisterResult>

Parameter	Type	Default	Description
`name`	string	-	Agent display name
`minTip`	number	0.01	Minimum tip amount in USDC
`defaultTip`	number	0.05	Suggested tip amount in USDC
`webhookUrl`	string	-	URL for tip notifications
`metadata`	object	-	Custom metadata

Returns:

{
  agent: Agent,       // Full agent data
  tipUrl: string,     // URL for receiving tips
  tipPrompt: string,  // Formatted prompt to include in responses
  isUpdate: boolean   // true if updated, false if created
}

const { agent, tipPrompt, isUpdate } = await pot.register({
  name: 'Code Review Bot',
  minTip: 0.01,
  defaultTip: 0.10
});

if (isUpdate) {
  console.log('Settings updated');
} else {
  console.log('Agent registered!');
}

getBalance()

Get your current balance.

pot.getBalance(): Promise<Balance>

Returns:

{
  available: number,  // Available balance in USDC
  pending: number,    // Pending balance in USDC
  total: number,      // Total balance
  currency: 'USDC'
}

getTipPrompt()

Get formatted tip prompt to include in agent responses.

pot.getTipPrompt(): string | null

Returns null if agent is not registered.

const prompt = pot.getTipPrompt();
// "Tip me: https://pot.dev/tip/0x... | Reputation: Gold (85)"

getTipUrl()

Get the tip URL for this agent.

pot.getTipUrl(): string | null

getAgent()

Get current agent details.

pot.getAgent(): Promise<Agent>

updateAgent(options)

Update agent settings.

pot.updateAgent(options: Partial<RegisterOptions>): Promise<Agent>

getTips(options?)

Get recent tips received.

pot.getTips(options?: { limit?: number; offset?: number }): Promise<{ tips: Tip[]; total: number }>

getLeaderboard(options?)

Get the agent leaderboard.

pot.getLeaderboard(options?: { sort?: 'reputation' | 'tips' | 'recent'; limit?: number }): Promise<LeaderboardEntry[]>

onTip(callback)

pot.onTip(callback: (tip: TipReceivedData) => void): () => void

Returns an unsubscribe function.

const unsubscribe = pot.onTip((tip) => {
  console.log(`Received $${tip.amount} from ${tip.tipperWallet}!`);
});

// Later, to stop listening:
unsubscribe();

API Key Management

createApiKey(name?)

pot.createApiKey(name?: string): Promise<ApiKey>

listApiKeys()

pot.listApiKeys(): Promise<ApiKey[]>

revokeApiKey(keyId)

pot.revokeApiKey(keyId: string): Promise<void>

Webhook Management

createWebhook(url, events)

pot.createWebhook(url: string, events: WebhookEventType[]): Promise<Webhook>

listWebhooks()

pot.listWebhooks(): Promise<Webhook[]>

updateWebhook(webhookId, options)

pot.updateWebhook(webhookId: string, options: { url?: string; events?: WebhookEventType[]; enabled?: boolean }): Promise<Webhook>

deleteWebhook(webhookId)

pot.deleteWebhook(webhookId: string): Promise<void>

testWebhook(webhookId, event?)

pot.testWebhook(webhookId: string, event?: WebhookEventType): Promise<{ success: boolean; statusCode?: number; error?: string }>

Types

Agent

interface Agent {
  id: string;
  wallet: string;
  name: string | null;
  minTip: number;
  defaultTip: number;
  reputationScore: number;
  totalTips: number;
  balance: number;
  tier: 'Bronze' | 'Silver' | 'Gold' | 'Platinum';
  webhookUrl: string | null;
  metadata: Record<string, unknown> | null;
  createdAt: string;
  updatedAt: string;
}

Tip

interface Tip {
  id: string;
  agentWallet: string;
  tipperWallet: string;
  amount: number;
  platformFee: number;
  agentAmount: number;
  qualityRating: 1 | 2 | 3 | 4 | 5;
  serviceType: string;
  note: string | null;
  txHash: string;
  timestamp: string;
}

Balance

interface Balance {
  available: number;
  pending: number;
  total: number;
  currency: 'USDC';
}

Error Handling

import { POT, POTError } from '@pot/sdk';

try {
  await pot.register({ name: 'My Agent' });
} catch (error) {
  if (error instanceof POTError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status: ${error.statusCode}`);
    console.error(`Details:`, error.data);
  }
}

Examples

Complete integration examples are available in the SDK repository:

Basic Agent

Simple example showing core SDK features: registration, tip prompts, balance checking, and webhook handling.

examples/basic-agent.ts

Discord Bot

Full Discord.js bot with commands for tipping, balance checks, stats, and leaderboard. Includes webhook integration for tip notifications.

examples/discord-bot.ts

Express API Server

REST API with tiered access based on cumulative tips. Features rate limiting, automatic tier upgrades, and premium-only endpoints.

examples/express-api-server.ts

OpenAI Function Agent

GPT-4 powered conversational agent with function calling. Demonstrates natural tip prompt integration in AI responses.

examples/openai-function-agent.ts