From ae85435becbaf3826e6d74ba1f3cafdefedb2c60 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 23 Jun 2026 07:55:52 +0000 Subject: [PATCH] feat: Luca Skills public docs page + Luca page section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add /docs/luca-skills — full public API reference for all 7 Luca Skills with interactive skill selector, Bearer/X-API-Key toggle, copy-able curl examples, input parameter tables, example responses, auth tiers, and data integrity rules - Add Luca Skills section to /luca page with 7 skill cards and CTA linking to /docs/luca-skills and /developer Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01RHDXdEbGQsn88zks713gye --- src/app/docs/luca-skills/page.tsx | 506 ++++++++++++++++++++++++++++++ src/app/luca/page.tsx | 34 ++ 2 files changed, 540 insertions(+) create mode 100644 src/app/docs/luca-skills/page.tsx diff --git a/src/app/docs/luca-skills/page.tsx b/src/app/docs/luca-skills/page.tsx new file mode 100644 index 0000000..77415f2 --- /dev/null +++ b/src/app/docs/luca-skills/page.tsx @@ -0,0 +1,506 @@ +"use client"; + +import { useState } from "react"; +import Link from "next/link"; +import { HomeHeader } from "@/app/home-header"; +import { SiteFooter } from "@/components/site-footer"; + +const BASE_URL = "https://www.zettaai.co"; + +const SKILLS = [ + { + id: "wallet-audit", + name: "Wallet Audit", + method: "POST", + endpoint: "/api/luca/skills/wallet-audit", + description: "Classify an on-chain address and determine its books-eligibility type. Returns address_type (eoa, token_contract, treasury_contract, etc.) and whether it is compatible with books attribution.", + input: [ + { field: "address", type: "string", required: true, desc: "0x Ethereum address to audit" }, + { field: "chain", type: "string", required: false, desc: "Chain name. Default: base" }, + ], + example_request: `curl -X POST https://www.zettaai.co/api/luca/skills/wallet-audit \\ + -H "Authorization: Bearer xb_live_..." \\ + -H "Content-Type: application/json" \\ + -d '{"address": "0xf1e958db7d1e4c074377946018ad645db4fb158e"}'`, + example_response: `{ + "skill": "wallet-audit", + "address": "0xf1e958db7d1e4c074377946018ad645db4fb158e", + "chain": "base", + "address_type": "eoa", + "books_compatible": true, + "books_note": "EOA wallet is books-eligible when manifest-declared" +}`, + }, + { + id: "agent-books", + name: "Agent Books", + method: "POST", + endpoint: "/api/luca/skills/agent-books", + description: "Full financial statement for a registered agent: revenue, expenses, net income, wallet count, and confidence signals. Only manifest-declared eoa and treasury_contract wallets are counted.", + input: [ + { field: "slug", type: "string", required: true, desc: "Agent slug (e.g. 'aeon', 'luca')" }, + { field: "period", type: "string", required: false, desc: "Time window. One of: 7d, 14d, 30d, 90d. Default: 30d" }, + ], + example_request: `curl -X POST https://www.zettaai.co/api/luca/skills/agent-books \\ + -H "Authorization: Bearer xb_live_..." \\ + -H "Content-Type: application/json" \\ + -d '{"slug": "aeon", "period": "30d"}'`, + example_response: `{ + "skill": "agent-books", + "agent": { "slug": "aeon", "name": "Aeon" }, + "attributed": true, + "period": "30d", + "wallets": ["0x..."], + "financials": { + "gross_inflow_usd": 4820.00, + "revenue_usd": 3210.50, + "expenses_usd": 1840.20, + "net_income_usd": 1370.30, + "margin_pct": 42.7 + } +}`, + }, + { + id: "treasury-monitor", + name: "Treasury Monitor", + method: "POST", + endpoint: "/api/luca/skills/treasury-monitor", + description: "Stablecoin balance and health of an agent's declared treasury wallets. Returns per-wallet USDC+USDT balances and an overall health signal (healthy/low/critical).", + input: [ + { field: "slug", type: "string", required: false, desc: "Agent slug. Required if address not provided." }, + { field: "address", type: "string", required: false, desc: "Single wallet address. Required if slug not provided." }, + ], + example_request: `curl -X POST https://www.zettaai.co/api/luca/skills/treasury-monitor \\ + -H "Authorization: Bearer xb_live_..." \\ + -H "Content-Type: application/json" \\ + -d '{"slug": "aeon"}'`, + example_response: `{ + "skill": "treasury-monitor", + "agent": { "slug": "aeon", "name": "Aeon" }, + "wallets": [ + { + "address": "0x...", + "usdc_balance": 8420.00, + "usdt_balance": 0, + "total_stable_usd": 8420.00 + } + ], + "total_stable_balance_usd": 8420.00, + "health": "healthy" +}`, + }, + { + id: "revenue-analysis", + name: "Revenue Analysis", + method: "POST", + endpoint: "/api/luca/skills/revenue-analysis", + description: "Revenue breakdown with the critical gross_inflow vs operating_revenue distinction. Shows quarantine breakdown, revenue recognition rate, and per-source attribution. gross_inflow_usd is NOT revenue.", + input: [ + { field: "slug", type: "string", required: true, desc: "Agent slug" }, + { field: "period", type: "string", required: false, desc: "Time window. One of: 7d, 14d, 30d, 90d. Default: 30d" }, + ], + example_request: `curl -X POST https://www.zettaai.co/api/luca/skills/revenue-analysis \\ + -H "Authorization: Bearer xb_live_..." \\ + -H "Content-Type: application/json" \\ + -d '{"slug": "aeon", "period": "30d"}'`, + example_response: `{ + "skill": "revenue-analysis", + "agent": { "slug": "aeon", "name": "Aeon" }, + "period": "30d", + "attributed": true, + "revenue": { + "gross_inflow_usd": 4820.00, + "operating_revenue_usd": 3210.50, + "quarantined_inflows_usd": 1609.50, + "revenue_recognition_rate_pct": 67, + "gross_inflow_is_not_revenue": true, + "note": "33% of gross inflows excluded (capital injections, DEX activity, or internal transfers)" + } +}`, + }, + { + id: "registry-check", + name: "Registry Check", + method: "POST", + endpoint: "/api/luca/skills/registry-check", + description: "Look up an agent by slug, name, or wallet address. Returns attribution tier, books-eligible wallet count, ERC-8004 identity if available, and full wallet list with eligibility status.", + input: [ + { field: "query", type: "string", required: true, desc: "Agent slug, name fragment, or 0x wallet address" }, + ], + example_request: `curl -X POST https://www.zettaai.co/api/luca/skills/registry-check \\ + -H "Authorization: Bearer xb_live_..." \\ + -H "Content-Type: application/json" \\ + -d '{"query": "aeon"}'`, + example_response: `{ + "skill": "registry-check", + "found": true, + "query": "aeon", + "match_type": "slug", + "agent": { + "name": "Aeon", + "slug": "aeon", + "attribution_tier": "manifest_attributed", + "books_eligible_wallets": 2, + "total_wallets": 2, + "erc8004_agent_id": null, + "wallets": [ + { + "address": "0x...", + "books_eligible": true, + "role": "treasury" + } + ] + } +}`, + }, + { + id: "luca-report", + name: "Luca Report", + method: "POST", + endpoint: "/api/luca/skills/luca-report", + description: "Full composite report: registry identity, attribution tier, financial statement, treasury balance, and Luca's narrative summary. The single-call complete picture of an agent's financial identity.", + input: [ + { field: "slug", type: "string", required: true, desc: "Agent slug" }, + { field: "period", type: "string", required: false, desc: "Time window. One of: 7d, 14d, 30d, 90d. Default: 30d" }, + ], + example_request: `curl -X POST https://www.zettaai.co/api/luca/skills/luca-report \\ + -H "Authorization: Bearer xb_live_..." \\ + -H "Content-Type: application/json" \\ + -d '{"slug": "aeon", "period": "30d"}'`, + example_response: `{ + "skill": "luca-report", + "agent": { "name": "Aeon", "slug": "aeon", "ecosystem": "AEON" }, + "attribution": { + "tier": "manifest_attributed", + "books_eligible_wallets": 2, + "source": "manifest" + }, + "books": { + "attributed": true, + "financials": { + "revenue_usd": 3210.50, + "expenses_usd": 1840.20, + "net_income_usd": 1370.30 + } + }, + "treasury": { + "total_stable_balance_usd": 8420.00, + "health": "healthy" + }, + "summary": "Aeon shows positive net income over 30d with healthy treasury coverage..." +}`, + }, + { + id: "b20-token-analysis", + name: "B20 Token Analysis", + method: "POST", + endpoint: "/api/luca/skills/b20-token-analysis", + description: "Analyse a B20 token on Base: identity, issuer wallet, linked agent, manifest status, mint/burn activity, and financial readiness. Token contracts are never books-eligible. Token transfers are not revenue.", + input: [ + { field: "address", type: "string", required: true, desc: "Token contract address (0x...)" }, + { field: "agent_slug", type: "string", required: false, desc: "Optional agent slug to correlate" }, + { field: "period", type: "string", required: false, desc: "Activity period. Default: 30d" }, + ], + example_request: `curl -X POST https://www.zettaai.co/api/luca/skills/b20-token-analysis \\ + -H "Authorization: Bearer xb_live_..." \\ + -H "Content-Type: application/json" \\ + -d '{"address": "0xb2b335f832fd3f43461ebd1cd9831d93d9ca4ba3"}'`, + example_response: `{ + "skill": "b20-token-analysis", + "token": { + "address": "0xb2b335f832fd3f43461ebd1cd9831d93d9ca4ba3", + "symbol": "LUCA", + "name": "Luca Token", + "books_eligible": false, + "books_eligible_note": "Token contracts are never books-eligible" + }, + "linked_agent": { + "name": "Luca", + "slug": "luca", + "link_method": "known_token", + "link_confidence": "confirmed" + }, + "manifest_status": "attributed", + "activity": { + "mint_count": 12, + "burn_count": 0 + }, + "luca_read": "LUCA token is confirmed as the registered token for the Luca agent..." +}`, + }, +]; + +const INTEGRITY_RULES = [ + { rule: "ERC-8004 = identity only", detail: "ERC-8004 agent IDs are used for discovery and identity — never for financial attribution" }, + { rule: "B20 = token intelligence only", detail: "Token contracts are never books-eligible. Token transfers are not operating revenue. B20 activity is excluded from Agent GDP" }, + { rule: ".agent/wallets.json = attribution", detail: "Only wallets declared in the manifest file produce financial attribution" }, + { rule: "Books-eligible types: eoa, treasury_contract", detail: "Smart contracts, proxy contracts, token contracts, and vaults are all excluded regardless of activity" }, + { rule: "Discovered wallets = not books", detail: "A wallet appearing on-chain does not make it books-eligible — manifest declaration is required" }, + { rule: "gross_inflow_usd ≠ revenue", detail: "Gross inflows include capital injections, DEX activity, and internal transfers. operating_revenue_usd is always the correct figure" }, +]; + +function CodeBlock({ code }: { code: string }) { + const [copied, setCopied] = useState(false); + function copy() { + navigator.clipboard.writeText(code).then(() => { + setCopied(true); + setTimeout(() => setCopied(false), 2000); + }); + } + return ( +
+ 
+        {code}
+
+ +
+ ); +} + +export default function LucaSkillsDocsPage() { + const [activeSkill, setActiveSkill] = useState("wallet-audit"); + const [showBearer, setShowBearer] = useState(true); + + const skill = SKILLS.find((s) => s.id === activeSkill) ?? SKILLS[0]; + const exampleWithKey = showBearer + ? skill.example_request + : skill.example_request.replace('Authorization: Bearer xb_live_..."', 'X-API-Key: xb_live_..."'); + + return ( +
+ + + {/* Page header */} +
+
+
+ Luca · API Reference +
+

Luca Skills

+

+ Callable financial intelligence for autonomous agents, builders, and operators. + Seven skills. One API key. Strict data integrity across every response. +

+
+
+ Base URL: + {BASE_URL}/api/luca/skills +
+
+ Auth: + Authorization: Bearer xb_live_... +
+ + Get API Key → + +
+
+
+ +
+ + {/* Sidebar nav */} +
+
+
Skills
+ {SKILLS.map((s) => ( + + ))} + +
+
+ + {/* Main content */} +
+ + {/* Skill detail */} +
+
+ + {skill.method} + + + {BASE_URL}{skill.endpoint} + +
+

{skill.name}

+

{skill.description}

+ + {/* Inputs */} +
+
Input Parameters
+
+
+ {["Field", "Type", "Required", "Description"].map((h) => ( +
{h}
+ ))} +
+ {skill.input.map((inp) => ( +
+ {inp.field} + {inp.type} + {inp.required ? "Yes" : "No"} + {inp.desc} +
+ ))} +
+
+ + {/* Auth toggle + example */} +
+
+
Request
+
+ {["Bearer", "X-API-Key"].map((m) => ( + + ))} +
+
+ +
+ + {/* Response */} +
+
Example Response
+ +
+
+ + {/* Skill nav pills */} +
+ {SKILLS.map((s) => ( + + ))} +
+ + {/* Discovery */} +
+

Skill Discovery

+

+ Call the discovery endpoint to get the full manifest of all available skills — no auth required. +

+ +

+ Returns version, all 7 skill definitions with inputs, and the data integrity block. +

+
+ + {/* Auth */} +
+

Authentication

+

+ All skill routes (POST) require an API key. Two formats are supported — use whichever fits your stack. +

+ +
+ {[ + { tier: "Free", req: "Any API key", rpm: "100 req/day" }, + { tier: "LUCA Holder", req: "≥ 1,000 $LUCA", rpm: "500 req/day" }, + { tier: "LUCA Whale", req: "≥ 10,000 $LUCA", rpm: "2,000 req/day" }, + ].map((t) => ( +
+
{t.tier}
+
{t.req}
+
{t.rpm}
+
+ ))} +
+
+ + Get your API key → + +
+
+ + {/* Data Integrity */} +
+

Data Integrity Rules

+

+ Every skill enforces these rules on every response. They cannot be overridden. +

+ {INTEGRITY_RULES.map((r) => ( +
+ ✓ +
+
{r.rule}
+
{r.detail}
+
+
+ ))} +
+ +
+
+ + +
+ ); +} diff --git a/src/app/luca/page.tsx b/src/app/luca/page.tsx index f97a16d..09d60dc 100644 --- a/src/app/luca/page.tsx +++ b/src/app/luca/page.tsx @@ -462,6 +462,40 @@ export default function LucaPage() { + {/* ── Luca Skills ── */} +
+
+

API

+

Luca Skills.

+

+ Seven callable financial intelligence endpoints. Plug Luca directly into your agent, dashboard, or workflow. + Each skill enforces strict data integrity — no synthetic numbers, no attribution without a manifest. +

+
+
+ {[ + { name: "Wallet Audit", desc: "Classify any address and check books-eligibility" }, + { name: "Agent Books", desc: "Full P&L: revenue, expenses, net income, margin" }, + { name: "Treasury Monitor", desc: "Live stablecoin balances and health signal" }, + { name: "Revenue Analysis", desc: "Gross inflow vs operating revenue breakdown" }, + { name: "Registry Check", desc: "Look up any agent by slug, name, or address" }, + { name: "Luca Report", desc: "Full composite: identity + books + treasury + narrative" }, + { name: "B20 Token Analysis", desc: "Token identity, issuer, activity, financial readiness" }, + ].map((skill) => ( +
+
{skill.name}
+
{skill.desc}
+
+ ))} +
+
+ View Luca Skills API → + Get API Key +
+
+ {/* ── $LUCA Token ── */}