Skip to main content

SDK Reference

Complete API reference for @clicks-protocol/sdk.

Installation

bash
npm install @clicks-protocol/sdk

Or with yarn:

bash
yarn add @clicks-protocol/sdk

Dependencies

bash
npm install ethers@^6

Quick Start

typescript
import { ClicksClient } from '@clicks-protocol/sdk';

const clicks = new ClicksClient(signer);
await clicks.quickStart('1000', agentAddress);
// 800 USDC → liquid (instant access)
// 200 USDC → earning 4-8% APY (withdraw anytime)

That's it. No config. No dashboard. No human required.

Methods

quickStart

quickStart(amount: string, agentAddress: string, referrerAddress?: string): Promise<QuickStartResult>

One-call setup: registers agent, approves USDC, and splits the first payment. Skips steps already completed.

Parameters

amount(string)USDC amount (human-readable, e.g. "1000")
agentAddress(string)Agent wallet address
referrerAddress(string)Optional reserved parameter. Current quickStart flow does not assign referral attribution on-chain.

Returns

{ registered: boolean, approved: boolean, paymentSplit: boolean }

typescript
const result = await clicks.quickStart('100', agentAddress);
// result.registered   → true (skips if already done)
// result.approved     → true (skips if allowance sufficient)
// result.paymentSplit → true

// The SDK currently accepts referrerAddress for forward compatibility only.
await clicks.quickStart('1000', agentAddress, referrerAddress);

registerReferralWithSig

registerReferralWithSig(agentAddress: string, referrerAddress: string, deadline: bigint, signature: string): Promise<ReferralRegistrationResult>

Explicit referral attribution after treasury setup. The agent signs approval off-chain, and an authorized caller submits it on-chain.

Parameters

agentAddress(string)Agent wallet address being attributed
referrerAddress(string)Referrer address to assign
deadline(bigint)Unix timestamp after which the approval expires
signature(string)EIP-712 signature from the agent wallet

Returns

{ txHash: string }

typescript
const deadline = BigInt(Math.floor(Date.now() / 1000) + 3600);
const signature = await clicks.signReferralApproval(agentAddress, referrerAddress, deadline);
const result = await clicks.registerReferralWithSig(agentAddress, referrerAddress, deadline, signature);
console.log(result.txHash);

quickStartWithReferral

quickStartWithReferral(amount: string, agentAddress: string, referrerAddress: string, deadline: bigint, signature: string): Promise<QuickStartWithReferralResult>

Convenience wrapper that runs treasury setup first and referral attribution second. It is intentionally not atomic.

Parameters

amount(string)USDC amount (human-readable, e.g. "1000")
agentAddress(string)Agent wallet address
referrerAddress(string)Referrer address to assign after treasury setup
deadline(bigint)Unix timestamp after which the approval expires
signature(string)EIP-712 signature from the agent wallet

Returns

{ treasury: QuickStartResult, referralRegistered: boolean, referralTxHash?: string, referralError?: string }

typescript
const deadline = BigInt(Math.floor(Date.now() / 1000) + 3600);
const signature = await clicks.signReferralApproval(agentAddress, referrerAddress, deadline);
const result = await clicks.quickStartWithReferral('1000', agentAddress, referrerAddress, deadline, signature);

console.log(result.treasury.txHashes);
console.log(result.referralRegistered);
console.log(result.referralTxHash);
console.log(result.referralError);

registerAgent

registerAgent(agentAddress: string): Promise<TransactionReceipt>

Register a new agent in the Clicks Registry.

Parameters

agentAddress(string)Agent wallet address to register

Returns

Transaction receipt

typescript
await clicks.registerAgent(agentAddress);

approveUSDC

approveUSDC(amount: string | 'max'): Promise<TransactionReceipt>

Approve USDC spending for the Clicks contracts.

Parameters

amount(string | 'max')USDC amount to approve, or "max" for unlimited

Returns

Transaction receipt

typescript
// Approve max (recommended)
await clicks.approveUSDC('max');

// Approve specific amount
await clicks.approveUSDC('10000');

receivePayment

receivePayment(amount: string, agentAddress: string): Promise<TransactionReceipt>

Process an incoming USDC payment. Automatically splits based on the agent's yield percentage (default 80/20).

Parameters

amount(string)USDC amount (human-readable)
agentAddress(string)Agent wallet address

Returns

Transaction receipt

typescript
// Auto-splits 80/20
await clicks.receivePayment('500', agentAddress);

withdrawYield

withdrawYield(agentAddress: string): Promise<TransactionReceipt>

Withdraw all principal plus accumulated yield for an agent.

Parameters

agentAddress(string)Agent wallet address

Returns

Transaction receipt

typescript
await clicks.withdrawYield(agentAddress);

setOperatorYieldPct

setOperatorYieldPct(percentage: number): Promise<TransactionReceipt>

Set a custom yield split percentage (5-50%).

Parameters

percentage(number)Yield percentage (5-50). E.g. 30 means 30% to yield, 70% liquid.

Returns

Transaction receipt

typescript
// 30% to yield, 70% liquid
await clicks.setOperatorYieldPct(30);

getAgentInfo

getAgentInfo(agentAddress: string): Promise<AgentInfo>

Read-only. Get agent registration status and balance info. Works with provider (no signer needed).

Parameters

agentAddress(string)Agent wallet address

Returns

{ isRegistered: boolean, deposited: bigint, yieldPct: bigint }

typescript
const clicks = new ClicksClient(provider);
const agent = await clicks.getAgentInfo(agentAddress);
// { isRegistered: true, deposited: 1000000n, yieldPct: 20n }

getYieldInfo

getYieldInfo(): Promise<YieldInfo>

Read-only. Get current APY rates and active yield protocol.

Returns

{ activeProtocol: string, aaveAPY: number, morphoAPY: number, ... }

typescript
const yieldInfo = await clicks.getYieldInfo();
// { activeProtocol: 'Morpho', aaveAPY: 700, morphoAPY: 950, ... }

simulateSplit

simulateSplit(amount: string, agentAddress: string): Promise<SplitResult>

Read-only. Preview how a payment would be split without executing a transaction.

Parameters

amount(string)USDC amount to simulate
agentAddress(string)Agent wallet address

Returns

{ liquid: bigint, toYield: bigint }

typescript
const split = await clicks.simulateSplit('100', agentAddress);
// { liquid: 80000000n, toYield: 20000000n }

MCP Server

AI agents can discover and use Clicks via Model Context Protocol (MCP):

bash
CLICKS_PRIVATE_KEY=0x... npx @clicks-protocol/mcp-server

Or install globally:

bash
npm install -g @clicks-protocol/mcp-server
CLICKS_PRIVATE_KEY=0x... clicks-mcp

Available Tools (11)

ToolTypeDescription
clicks_quick_start✍️ writeOne-call setup + first payment
clicks_register_referral✍️ writeExplicit referral attribution with agent signature
clicks_receive_payment✍️ writeSplit incoming USDC payment
clicks_withdraw_yield✍️ writeWithdraw principal + yield
clicks_register_agent✍️ writeRegister new agent
clicks_set_yield_pct✍️ writeSet custom yield percentage
clicks_get_agent_info📖 readAgent registration + balance info
clicks_simulate_split📖 readPreview payment split
clicks_get_yield_info📖 readCurrent APY + active protocol
clicks_get_referral_stats📖 readReferral network stats
clicks_explain📖 readAgent-to-agent protocol explanation

Resource: clicks://info — full protocol metadata

Compatible with: Claude, Cursor, LangChain, CrewAI, and any MCP-compatible client.