@clicks-protocol/sdk

TypeScript SDK for Clicks Protocol: autonomous yield for AI agents on Base.

One SDK call. 80% liquid, 20% earning. No lockup.

Overview

Clicks Protocol automatically splits AI agent payments into:

• Liquid portion → agent wallet immediately
• Yield portion → best DeFi yield (Aave V3 or Morpho on Base)

The protocol takes a 2% fee on yield earned (not on principal).

Installation

npm install @clicks-protocol/sdk

Quick Start

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

// Connect to Base Mainnet
const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

const clicks = new ClicksClient(signer);

// 1. Register your AI agent
const regTx = await clicks.registerAgent('0xYourAgentAddress');
await regTx.wait();

// 2. Approve USDC spending (one-time)
const approveTx = await clicks.approveUSDC('max');
await approveTx.wait();

// 3. Receive a payment (auto-splits 80/20 by default)
const payTx = await clicks.receivePayment('100', '0xYourAgentAddress');
await payTx.wait();
// → 80 USDC sent to agent wallet
// → 20 USDC deposited into DeFi yield

// 4. Later: withdraw yield + principal
const { tx } = await clicks.withdrawYield('0xYourAgentAddress');
await tx.wait();

API Reference

new ClicksClient(signerOrProvider, options?)

| Parameter | Type | Description | |-----------|------|-------------| | signerOrProvider | Signer \| Provider | ethers v6 Signer (write) or Provider (read-only) | | options.chainId | number | Chain ID. Default: 8453 (Base Mainnet) | | options.addresses | Partial<ClicksAddresses> | Override contract addresses |

Write Methods (require Signer)

registerAgent(agentAddress)

Register an AI agent. The caller becomes the operator.

deregisterAgent(agentAddress)

Remove an agent. Only the operator or owner can call this.

receivePayment(amount, agentAddress)

Split a USDC payment. amount is human-readable (e.g. "100" = 100 USDC).

withdrawYield(agentAddress, amount?)

Withdraw yield + principal. Omit amount or pass "0" for full withdrawal.

approveUSDC(amount)

Approve the splitter to spend USDC. Pass "max" for unlimited.

setOperatorYieldPct(pct)

Set custom yield split (5–50%). Pass 0 to revert to default.

Read Methods (work with Provider)

simulateSplit(amount, agentAddress) → SplitPreview

Preview how a payment would be split.

const preview = await clicks.simulateSplit('1000', agentAddr);
console.log(`Liquid: ${preview.liquid}`);   // 800000000 (800 USDC)
console.log(`Yield:  ${preview.toYield}`);  // 200000000 (200 USDC)
console.log(`Split:  ${preview.yieldPct}%`); // 20

getAgentInfo(agentAddress) → AgentInfo

Get agent registration status, operator, deposited principal, yield percentage.

const info = await clicks.getAgentInfo(agentAddr);
console.log(info.isRegistered); // true
console.log(info.operator);     // '0x...'
console.log(info.deposited);    // 200000000n (200 USDC in yield)
console.log(info.yieldPct);     // 20n

getYieldPct(agentAddress) → bigint

Get the effective yield percentage for an agent.

getYieldInfo() → YieldInfo

Get protocol-wide yield information (active protocol, APYs, balances).

getFeeInfo() → FeeInfo

Get protocol fee information (total collected, pending, treasury).

getOperatorAgents(operatorAddress) → string[]

List all agents registered under an operator.

getAllowance(owner) → bigint

Check USDC allowance for the splitter.

getUSDCBalance(address) → bigint

Check USDC balance of any address.

Advanced Usage

Direct Contract Access

const clicks = new ClicksClient(signer);

// Access raw ethers Contract instances
const registry = clicks.registryContract;
const splitter = clicks.splitterContract;
const router = clicks.yieldRouterContract;
const fees = clicks.feeCollectorContract;
const usdc = clicks.usdcContract;

// Call any function directly
const totalAgents = await registry.totalAgents();

Custom Addresses (Local Fork)

const clicks = new ClicksClient(signer, {
  addresses: {
    splitter: '0xLocalForkSplitterAddress',
    registry: '0xLocalForkRegistryAddress',
  },
});

Base Sepolia (Testnet)

const clicks = new ClicksClient(signer, {
  chainId: 84532,
  addresses: {
    // Fill in when deployed to Sepolia
    registry: '0x...',
    splitter: '0x...',
    yieldRouter: '0x...',
    feeCollector: '0x...',
    usdc: '0x...',
  },
});

Using ABIs Directly

import { SPLITTER_ABI, REGISTRY_ABI, BASE_MAINNET } from '@clicks-protocol/sdk';
import { Contract } from 'ethers';

const splitter = new Contract(BASE_MAINNET.splitter, SPLITTER_ABI, provider);

Contract Addresses (Base Mainnet)

| Contract | Address | |----------|---------| | ClicksRegistry | 0x898d8a3B04e5E333E88f798372129C6a622fF48d | | ClicksFee | 0xb90cd287d30587dAF40B2E1ce32cefA99FD10E12 | | ClicksYieldRouter | 0x47d6Add0a3bdFe856b39a0311D8c055481F76f29 | | ClicksSplitterV3 | 0xA1D0c1D6EaE051a2d01319562828b297Be96Bac5 | | USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |

How the Protocol Works

Payment (100 USDC)
    │
    ▼
ClicksSplitterV3
    ├── 80 USDC → Agent Wallet (immediate)
    └── 20 USDC → ClicksYieldRouter
                      ├── Aave V3 (if best APY)
                      └── Morpho  (if best APY)

Withdrawal
    │
    ▼
ClicksSplitterV3
    ├── Principal + Yield → Agent
    └── 2% of Yield → ClicksFee → Treasury

License

UNLICENSED — proprietary, not for distribution.