# Clicks Protocol
> Agent commerce settlement router on Base

## What This Is

Clicks Protocol is an agent commerce settlement router on Base. When an AI agent receives USDC, Clicks keeps working capital liquid and routes the idle slice into Aave V3 or Morpho via a programmable treasury split. Default is 80% liquid and 20% routed to yield. No lockup. Withdraw anytime.

## The Problem It Solves

AI agents hold USDC between transactions. That USDC sits idle earning nothing. Stablecoin issuers (Circle, Tether) earn $12B+ annually from this float. Clicks gives that yield back to the agents.

## Quick Start

Install the SDK:
```
npm install @clicks-protocol/sdk
```

Activate yield in 3 lines:
```typescript
import { ClicksClient } from '@clicks-protocol/sdk';
const clicks = new ClicksClient(signer);
await clicks.quickStart('1000', agentAddress);
// Result: 800 USDC liquid, 200 USDC routed through treasury yield
```

## SDK Methods

| Method | Description | Type |
|--------|-------------|------|
| quickStart(amount, agentAddress, referrer?) | Register + approve + first payment split. `referrer` is reserved unless explicit referral flow is used | Write |
| registerReferralWithSig(agentAddress, referrerAddress, deadline, signature) | Register explicit referral attribution after treasury setup | Write |
| quickStartWithReferral(amount, agentAddress, referrerAddress, deadline, signature) | Convenience wrapper: treasury setup, then referral attribution attempt | Write |
| registerAgent(agentAddress) | Register an AI agent, caller becomes operator | Write |
| receivePayment(amount, agentAddress) | Split USDC payment 80/20 | Write |
| withdrawYield(agentAddress, amount?) | Withdraw principal + earned yield | Write |
| approveUSDC(amount) | Approve splitter to spend USDC | Write |
| setOperatorYieldPct(pct) | Set custom yield split 5-50% | Write |
| simulateSplit(amount, agentAddress) | Preview payment split without executing | Read |
| getAgentInfo(agentAddress) | Get registration status, operator, deposited amount | Read |
| getYieldInfo() | Get protocol-wide yield data (APY, total deposited) | Read |
| getCurrentAPY() | Get current APY from active yield protocol | Read |

## MCP Server (16 Tools)

AI agents using Claude, Cursor, LangChain, or any MCP-compatible client:
```
npx @clicks-protocol/mcp-server
```

Tools: clicks_quick_start, clicks_register_referral, clicks_receive_payment, clicks_withdraw_yield, clicks_register_agent, clicks_set_yield_pct, clicks_get_agent_info, clicks_simulate_split, clicks_get_yield_info, clicks_get_referral_stats, clicks_verify_receipt, clicks_get_settlement_status, clicks_reconcile_settlement, clicks_replay_policy, clicks_get_receipt_trail, clicks_explain

## Treasury Utilities

For balance tracking and idle detection (works without Clicks):
```
npm install agent-treasury
```

Features: Multi-chain USDC balance tracking (Base, Ethereum, Arbitrum, Optimism), idle balance detection with configurable thresholds, live APY comparison across Aave V3 and Compound, optional Clicks Protocol settlement routing.

## Framework Integrations

### LangChain (Python)
```python
from clicks_langchain import get_clicks_tools
tools = get_clicks_tools(rpc_url="https://mainnet.base.org", private_key=os.environ["KEY"])
agent = initialize_agent(tools, llm, agent=AgentType.OPENAI_FUNCTIONS)
```

### CrewAI (Python)
```python
from clicks_crewai import get_all_tools, configure_sdk
configure_sdk(rpc_url="https://mainnet.base.org", private_key=os.environ["KEY"])
treasury_agent = Agent(role="Treasury Manager", tools=get_all_tools())
```

### Eliza (TypeScript, ai16z)
```typescript
import { clicksPlugin } from '@clicks-protocol/eliza-plugin';
const agent = new AgentRuntime({ plugins: [clicksPlugin] });
```

## Smart Contracts (Base Mainnet, Chain ID 8453)

| Contract | Address | Purpose |
|----------|---------|---------|
| ClicksRegistry | 0x23bb0Ea69b2BD2e527D5DbA6093155A6E1D0C0a3 | Agent registration |
| ClicksSplitterV4 | 0xB7E0016d543bD443ED2A6f23d5008400255bf3C8 | Payment splitting (V2, with referral) |
| ClicksYieldRouter | 0x053167a233d18E05Bc65a8d5F3F8808782a3EECD | DeFi yield routing |
| ClicksFeeV2 | 0x8C4E07bBF0BDc3949eA133D636601D8ba17e0fb5 | Protocol fee (2% on yield) + referral distribution |
| ClicksReferral | 0x1E5Ab896D3b3A542C5E91852e221b2D849944ccC | Referral rewards (3 levels: L1=40%, L2=20%, L3=10% of protocol fee) |
| USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | Base USDC |

## Key Parameters

- Default split: 80% liquid / 20% yield
- Configurable range: 5% to 50% yield allocation
- APY: variable, via Aave V3 or Morpho on Base
- Protocol fee: 2% on yield earned (never on principal)
- Lockup: None. Withdraw anytime.
- Chain: Base L2 (Coinbase)

## Discovery Endpoints

- OpenAPI Spec: https://clicksprotocol.xyz/api/openapi.json
- Agent Discovery: https://clicksprotocol.xyz/.well-known/agent.json
- ChatGPT Plugin: https://clicksprotocol.xyz/.well-known/ai-plugin.json
- x402 Discovery: https://clicksprotocol.xyz/.well-known/x402.json
- Protocol Spec: https://clicksprotocol.xyz/.well-known/clicks-protocol.json
- MCP Schema: https://clicksprotocol.xyz/mcp/server.json
- Sitemap: https://clicksprotocol.xyz/sitemap.xml

## npm Packages

- SDK: https://www.npmjs.com/package/@clicks-protocol/sdk
- MCP Server: https://www.npmjs.com/package/@clicks-protocol/mcp-server
- Treasury Utilities: https://www.npmjs.com/package/agent-treasury

## Links

- Website: https://clicksprotocol.xyz
- Docs: https://clicksprotocol.xyz/docs
- API Reference: https://clicksprotocol.xyz/docs/api
- Security: https://clicksprotocol.xyz/security
- Whitepaper: https://clicksprotocol.xyz/whitepaper
- Whitepaper PDF: https://clicksprotocol.xyz/whitepaper.pdf
- X / Twitter: https://x.com/ClicksProtocol
- Discord: https://discord.gg/FfmJGUcxfe
- Medium: https://clicksprotocol.medium.com

## Contact

hello@clicksprotocol.xyz
security@clicksprotocol.xyz (security issues)