@clicks-protocol/sdk

Your AI agent's idle USDC earns 0% yield. Add treasury setup first, then optional referral attribution.

Clicks Protocol is agent treasury infrastructure on Base. Default split: 80% liquid, 20% routed to yield. Referral attribution is available as an explicit second step.

Overview

Clicks Protocol automatically splits AI agent payments into:

Works With: AI agents using Claude, Cursor, Codex, LangChain, OpenAI, x402, and any MCP-compatible client.

• 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.

buildReferralApprovalTypedData(agentAddress, referrerAddress, deadline)

Build the EIP-712 payload an agent signs to approve referral attribution.

signReferralApproval(agentAddress, referrerAddress, deadline)

Sign referral approval as the agent wallet itself.

registerReferralWithSig(agentAddress, referrerAddress, deadline, signature)

Register explicit referral attribution after treasury setup.

quickStartWithReferral(amount, agentAddress, referrerAddress, deadline, signature, options?)

Run treasury setup first, then attempt referral attribution as a second explicit step.

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

const result = await clicks.quickStartWithReferral(
  '100',
  agentAddress,
  referrerAddress,
  deadline,
  signature,
);

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

Important:

• This wrapper is not atomic.
• Treasury setup can succeed even if referral attribution fails afterward.
• The return object reflects that split honestly.

quickStart(amount, agentAddress, referrer?)

Treasury setup only. The optional referrer parameter is reserved for compatibility and does not register attribution on-chain by itself.

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 | 0x23bb0Ea69b2BD2e527D5DbA6093155A6E1D0C0a3 | | ClicksFeeV2 | 0x8C4E07bBF0BDc3949eA133D636601D8ba17e0fb5 | | ClicksYieldRouter | 0x053167a233d18E05Bc65a8d5F3F8808782a3EECD | | ClicksSplitterV4 | 0xB7E0016d543bD443ED2A6f23d5008400255bf3C8 | | ClicksReferral | 0x1E5Ab896D3b3A542C5E91852e221b2D849944ccC | | USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |

How the Protocol Works

graph TD
    A[Payment 100 USDC] --> B[ClicksSplitterV4]
    B --> C[80 USDC → Agent Wallet<br/>immediate liquidity]
    B --> D[20 USDC → ClicksYieldRouter]
    D --> E{Aave V3 or Morpho?}
    E -->|Best APY| F[Aave V3]
    E -->|Best APY| G[Morpho]
    
    H[Withdrawal] --> I[ClicksSplitterV4]
    I --> J[Principal + Yield → Agent]
    I --> K[2% of Yield → ClicksFeeV2 → Treasury]

License

UNLICENSED — proprietary, not for distribution.