From 3660a17162773f8535e374e52dd081be92a2780d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 23 Jun 2026 08:15:29 +0000 Subject: [PATCH 1/2] fix: replace remaining x402Books brand references with Zetta MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - /api page GitHub link: x402books-ai → zetta - tokens.ts comment: x402Books → Zetta - agent-books.ts audit note: x402Books → Zetta Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01RHDXdEbGQsn88zks713gye --- src/app/api/page.tsx | 2 +- src/lib/agent-books.ts | 2 +- src/lib/tokens.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/app/api/page.tsx b/src/app/api/page.tsx index 860ac21..ee41b14 100644 --- a/src/app/api/page.tsx +++ b/src/app/api/page.tsx @@ -95,7 +95,7 @@ export default function ApiPage() {

s + tx.amount_usd, 0); const aeonDiffNotes = [ - `x402Books operating revenue ($${round(operatingRevenueUsd).toLocaleString()}) = gross inflows ($${round(grossInflowUsd).toLocaleString()}) minus quarantined ($${round(quarantinedUsd).toLocaleString()}).`, + `Zetta operating revenue ($${round(operatingRevenueUsd).toLocaleString()}) = gross inflows ($${round(grossInflowUsd).toLocaleString()}) minus quarantined ($${round(quarantinedUsd).toLocaleString()}).`, `DEX swaps ($${round(dexUsd).toLocaleString()} across ${dexAudit.length} tx(s)) are excluded from all revenue and expense calculations.`, `Bridge transfers excluded; $${round(bridgeInflowUsd).toLocaleString()} in inbound bridge receipts were not counted as revenue.`, `${internalTxs.length} internal transfer(s) between this agent's declared wallets removed (treasury movement).`, diff --git a/src/lib/tokens.ts b/src/lib/tokens.ts index 3a96d9e..0436ff7 100644 --- a/src/lib/tokens.ts +++ b/src/lib/tokens.ts @@ -5,7 +5,7 @@ export const STABLECOIN_ADDRESSES = new Set([ "0x60a3e35cc302bfa44cb288bc5a4f316fdb1adb42", // EURC on Base ]); -// Tokens tracked in x402Books financial calculations. +// Tokens tracked in Zetta financial calculations. // Only ETH (native), WETH, USDC, USDT, and the agent's own project token count. // All other ERC-20s (memecoins, LP tokens, misc) are excluded to prevent GDP inflation. export const WETH_BASE = "0x4200000000000000000000000000000000000006"; From 4461d57f5823788fdeb646cef96733cb3eb50de2 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 23 Jun 2026 08:25:15 +0000 Subject: [PATCH 2/2] feat: add Luca Skills submission package for skills repository 7 skills under skills/zetta/, each with SKILL.md + references/api.md: - wallet-audit - agent-books - treasury-monitor - revenue-analysis - registry-check - luca-report - b20-token-analysis Each SKILL.md: description, endpoint, input/output schema, integrity rules, curl example, usage notes, limitations. Each api.md: full request/response spec with all error codes and field notes. Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01RHDXdEbGQsn88zks713gye --- skills/zetta/agent-books/SKILL.md | 101 +++++++++++++ skills/zetta/agent-books/references/api.md | 86 +++++++++++ skills/zetta/b20-token-analysis/SKILL.md | 137 ++++++++++++++++++ .../b20-token-analysis/references/api.md | 122 ++++++++++++++++ skills/zetta/luca-report/SKILL.md | 125 ++++++++++++++++ skills/zetta/luca-report/references/api.md | 124 ++++++++++++++++ skills/zetta/registry-check/SKILL.md | 132 +++++++++++++++++ skills/zetta/registry-check/references/api.md | 107 ++++++++++++++ skills/zetta/revenue-analysis/SKILL.md | 112 ++++++++++++++ .../zetta/revenue-analysis/references/api.md | 110 ++++++++++++++ skills/zetta/treasury-monitor/SKILL.md | 129 +++++++++++++++++ .../zetta/treasury-monitor/references/api.md | 110 ++++++++++++++ skills/zetta/wallet-audit/SKILL.md | 92 ++++++++++++ skills/zetta/wallet-audit/references/api.md | 80 ++++++++++ 14 files changed, 1567 insertions(+) create mode 100644 skills/zetta/agent-books/SKILL.md create mode 100644 skills/zetta/agent-books/references/api.md create mode 100644 skills/zetta/b20-token-analysis/SKILL.md create mode 100644 skills/zetta/b20-token-analysis/references/api.md create mode 100644 skills/zetta/luca-report/SKILL.md create mode 100644 skills/zetta/luca-report/references/api.md create mode 100644 skills/zetta/registry-check/SKILL.md create mode 100644 skills/zetta/registry-check/references/api.md create mode 100644 skills/zetta/revenue-analysis/SKILL.md create mode 100644 skills/zetta/revenue-analysis/references/api.md create mode 100644 skills/zetta/treasury-monitor/SKILL.md create mode 100644 skills/zetta/treasury-monitor/references/api.md create mode 100644 skills/zetta/wallet-audit/SKILL.md create mode 100644 skills/zetta/wallet-audit/references/api.md diff --git a/skills/zetta/agent-books/SKILL.md b/skills/zetta/agent-books/SKILL.md new file mode 100644 index 0000000..0701877 --- /dev/null +++ b/skills/zetta/agent-books/SKILL.md @@ -0,0 +1,101 @@ +# agent-books + +**Luca Skills by Zetta** — Callable financial intelligence for the agent economy. + +## What it does + +Returns the full financial statement for a registered agent: operating revenue, expenses, net income, wallet count, transaction breakdown, and confidence signals. Only manifest-declared `eoa` and `treasury_contract` wallets are counted — no discovered wallets, no token contracts. + +This is the canonical P&L for an autonomous agent on Base. + +## Endpoint + +``` +POST https://www.zettaai.co/api/luca/skills/agent-books +``` + +## Auth + +``` +Authorization: Bearer zt_live_... +``` +or +``` +X-API-Key: zt_live_... +``` + +Get a key at [zettaai.co/developer](https://www.zettaai.co/developer). + +## Input + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `slug` | string | Yes | Agent slug (e.g. `"aeon"`, `"luca"`) | +| `period` | string | No | Lookback window. One of: `7d`, `14d`, `30d`, `90d`. Default: `30d` | + +## Output — attributed + +```json +{ + "skill": "agent-books", + "attributed": true, + "agent": { "name": "AEON", "slug": "aeon", "ecosystem": "AEON" }, + "period": "30d", + "wallets": { + "eligible": 2, + "analyzed": 2, + "total": 5 + }, + "financials": { + "revenue_usd": 12450.00, + "expenses_usd": 3200.00, + "net_income_usd": 9250.00, + "gross_inflow_usd": 18000.00, + "margin_pct": 74.3, + "tx_count": 87 + }, + "confidence": "high", + "luca_summary": "AEON recorded $12,450.00 in operating revenue and $3,200.00 in expenses over 30d (87 transactions). Net income is positive at $9,250.00.", + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Output — unattributed (no manifest) + +```json +{ + "skill": "agent-books", + "attributed": false, + "agent": { "name": "SomeAgent", "slug": "someagent" }, + "reason": "No manifest-declared wallets found. Only wallets declared via .agent/wallets.json produce attributed books." +} +``` + +## Integrity rules + +- **Only manifest-declared wallets count.** Wallets in the registry but not in `.agent/wallets.json` produce zero books. +- **Only `eoa` and `treasury_contract` address types are books-eligible.** Token contracts declared in the manifest are silently excluded. +- **`gross_inflow_usd` is not revenue.** Gross inflows include capital injections, DEX receipts, and internal transfers that are quarantined. Use `revenue-analysis` for the full breakdown. +- Internal transfers between an agent's own wallets are excluded from both revenue and expenses. +- Agent GDP counts only operating revenue — not gross inflows. + +## Example + +```bash +curl -X POST https://www.zettaai.co/api/luca/skills/agent-books \ + -H "Authorization: Bearer zt_live_..." \ + -H "Content-Type: application/json" \ + -d '{"slug": "aeon", "period": "30d"}' +``` + +## Usage notes + +- Use `registry-check` first to find the correct slug if you only have a name or wallet address +- `attributed: false` means no manifest — not a data error. The agent needs to submit `.agent/wallets.json` +- `confidence` reflects how many wallets were analyzed vs declared: `high` = all eligible wallets covered + +## Limitations + +- Base chain only (USDC, USDT, ETH, WETH, and the agent's own project token) +- Books do not include off-chain revenue, CEX balances, or L2 chains other than Base +- Historical data starts from when the agent was first indexed in the Zetta registry diff --git a/skills/zetta/agent-books/references/api.md b/skills/zetta/agent-books/references/api.md new file mode 100644 index 0000000..1cf9198 --- /dev/null +++ b/skills/zetta/agent-books/references/api.md @@ -0,0 +1,86 @@ +# Agent Books — API Reference + +## Request + +``` +POST https://www.zettaai.co/api/luca/skills/agent-books +Content-Type: application/json +Authorization: Bearer zt_live_... +``` + +### Body + +```json +{ + "slug": "aeon", + "period": "30d" +} +``` + +| Field | Type | Required | Validation | +|-------|------|----------|-----------| +| `slug` | string | Yes | Lowercase agent slug | +| `period` | string | No | One of: `7d`, `14d`, `30d`, `90d`. Default: `30d` | + +## Response — 200 OK (attributed) + +```json +{ + "skill": "agent-books", + "attributed": true, + "agent": { + "name": "AEON", + "slug": "aeon", + "ecosystem": "AEON" + }, + "period": "30d", + "wallets": { + "eligible": 2, + "analyzed": 2, + "total": 5 + }, + "financials": { + "revenue_usd": 12450.00, + "expenses_usd": 3200.00, + "net_income_usd": 9250.00, + "gross_inflow_usd": 18000.00, + "margin_pct": 74.3, + "tx_count": 87, + "internal_tx_count": 4 + }, + "confidence": "high", + "breakdown": { + "revenue_by_source": [ + { "source": "0x...", "label": "External", "amount_usd": 12450.00 } + ], + "expenses_by_category": [ + { "category": "inference", "amount_usd": 2100.00 }, + { "category": "gas", "amount_usd": 1100.00 } + ] + }, + "luca_summary": "AEON recorded $12,450.00 in operating revenue and $3,200.00 in expenses over 30d (87 transactions). Net income is positive at $9,250.00.", + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Response — 200 OK (unattributed) + +```json +{ + "skill": "agent-books", + "attributed": false, + "agent": { "name": "SomeAgent", "slug": "someagent" }, + "reason": "No manifest-declared wallets found. Only wallets declared via .agent/wallets.json produce attributed books." +} +``` + +## Error responses + +| Status | Body | Cause | +|--------|------|-------| +| 400 | `{"error": "slug is required"}` | Missing slug | +| 400 | `{"error": "period must be 7d, 14d, 30d, or 90d"}` | Invalid period | +| 401 | `{"error": "Invalid API key."}` | Bad auth | +| 404 | `{"error": "Agent 'x' not found. Use registry-check skill to find the correct slug."}` | Agent not in registry | +| 429 | `{"error": "Rate limit reached..."}` | Rate limit | +| 500 | `{"error": "..."}` | Books computation failed | diff --git a/skills/zetta/b20-token-analysis/SKILL.md b/skills/zetta/b20-token-analysis/SKILL.md new file mode 100644 index 0000000..d6906e6 --- /dev/null +++ b/skills/zetta/b20-token-analysis/SKILL.md @@ -0,0 +1,137 @@ +# b20-token-analysis + +**Luca Skills by Zetta** — Callable financial intelligence for the agent economy. + +## What it does + +Analyses a B20 token on Base: identity, issuer wallet, linked agent, manifest attribution status, mint/burn activity, and a Luca narrative read. Enforces strict data integrity — token transfers are not revenue, token contracts are not operator wallets, and B20 activity is excluded from Agent GDP. + +Use this to understand a token's on-chain provenance and its relationship to an agent's financial identity, without conflating token activity with operating revenue. + +## Endpoint + +``` +POST https://www.zettaai.co/api/luca/skills/b20-token-analysis +``` + +## Auth + +``` +Authorization: Bearer zt_live_... +``` +or +``` +X-API-Key: zt_live_... +``` + +Get a key at [zettaai.co/developer](https://www.zettaai.co/developer). + +## Input + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `address` | string | Yes | Token contract address (0x...) | +| `agent_slug` | string | No | Optional agent slug to correlate with | +| `period` | string | No | Activity period label (informational only, does not filter data) | + +## Output + +```json +{ + "skill": "b20-token-analysis", + "token": { + "address": "0x...", + "name": "AEON Token", + "symbol": "AEON", + "decimals": 18, + "total_supply": "1000000000000000000000000", + "chain": "base", + "deployed_block": 12345678, + "issuer_wallet": "0x...", + "owner_wallet": "0x...", + "books_eligible": false, + "books_eligible_note": "Token contracts are never books-eligible" + }, + "linked_agent": { + "name": "AEON", + "slug": "aeon", + "link_method": "known_token", + "link_confidence": "confirmed", + "note": null + }, + "manifest_status": "attributed", + "manifest_note": "Issuer wallet is manifest-attributed", + "activity": { + "mint_count": 12, + "burn_count": 3, + "mint_volume_raw": "50000000000000000000000", + "burn_volume_raw": "1000000000000000000000", + "recent_mints": [...], + "recent_burns": [...], + "last_activity_at": "2026-06-20T14:22:00.000Z" + }, + "luca_read": "AEON Token (AEON) is a confirmed B20 asset linked to AEON via registry. 12 mint events and 3 burn events detected. Issuer wallet is manifest-attributed. Financial books require separate wallet attribution.", + "limitations": [ + "Token transfers are not operating revenue", + "Token contract is not an operator wallet", + "Issuer wallet (0x...) is not books-eligible unless declared in agent manifest", + "B20 activity is not included in Agent GDP", + "Holder concentration analysis requires a full transfer scan — not available in this endpoint" + ], + "data_integrity_warnings": [ + "gross_inflow_usd from token transfers ≠ operating revenue", + "Do not count B20 mint events as agent revenue", + "Token issuance is a financial event but not a revenue event" + ], + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +### `manifest_status` values + +| Value | Meaning | +|-------|---------| +| `attributed` | Issuer wallet is manifest-declared and confirmed | +| `candidate` | Issuer wallet matches a registry agent but manifest is not submitted | +| `none` | No agent link found | + +### `link_method` values + +| Value | Meaning | +|-------|---------| +| `known_token` | Token is declared in the agent's registry entry | +| `manifest` | Linked via `.agent/wallets.json` declaration | +| `erc8004` | Linked via ERC-8004 identity record | +| `admin` | Manually linked by Zetta admin | +| `none` | No confirmed link | + +## Integrity rules + +- `books_eligible: false` is hardcoded — token contracts are **never** books-eligible, regardless of manifest +- Token transfers (mint, burn, transfer events) are **not** operating revenue +- The issuer wallet is **not** automatically attributed — it must be declared in `.agent/wallets.json` to produce books +- B20 activity does not enter Agent GDP calculations +- `manifest_status: "attributed"` only applies to the token's agent link — not to the token contract itself + +## Example + +```bash +curl -X POST https://www.zettaai.co/api/luca/skills/b20-token-analysis \ + -H "Authorization: Bearer zt_live_..." \ + -H "Content-Type: application/json" \ + -d '{"address": "0xb2b335f832fd3f43461ebd1cd9831d93d9ca4ba3"}' +``` + +## Usage notes + +- If the token is already indexed in the Zetta B20 database, cached identity is used and only activity is fetched live — faster response +- If not indexed, a live Alchemy lookup is performed — slightly higher latency +- `luca_read` is a data-derived narrative — not a generative AI response +- `data_integrity_warnings` and `limitations` are always present — they are not error states + +## Limitations + +- Base chain only +- Activity scan covers recent mint/burn events; full historical activity requires a separate scan +- Holder distribution and concentration data are not available in this endpoint +- Token price data is not included diff --git a/skills/zetta/b20-token-analysis/references/api.md b/skills/zetta/b20-token-analysis/references/api.md new file mode 100644 index 0000000..6f3be6e --- /dev/null +++ b/skills/zetta/b20-token-analysis/references/api.md @@ -0,0 +1,122 @@ +# B20 Token Analysis — API Reference + +## Request + +``` +POST https://www.zettaai.co/api/luca/skills/b20-token-analysis +Content-Type: application/json +Authorization: Bearer zt_live_... +``` + +### Body + +```json +{ + "address": "0xb2b335f832fd3f43461ebd1cd9831d93d9ca4ba3", + "agent_slug": "luca", + "period": "30d" +} +``` + +| Field | Type | Required | Validation | +|-------|------|----------|-----------| +| `address` | string | Yes | Token contract address, must match `/^0x[0-9a-fA-F]{40}$/` | +| `agent_slug` | string | No | Optional agent slug to correlate. Does not affect analysis. | +| `period` | string | No | Informational only. Default: `30d`. | + +## Response — 200 OK + +```json +{ + "skill": "b20-token-analysis", + "token": { + "address": "0xb2b335f832fd3f43461ebd1cd9831d93d9ca4ba3", + "name": "LUCA", + "symbol": "LUCA", + "decimals": 18, + "total_supply": "1000000000000000000000000000", + "chain": "base", + "deployed_block": 12345678, + "issuer_wallet": "0x...", + "owner_wallet": "0x...", + "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", + "note": null + }, + "manifest_status": "attributed", + "manifest_note": "Issuer wallet is manifest-attributed", + "activity": { + "mint_count": 5, + "burn_count": 0, + "mint_volume_raw": "100000000000000000000000", + "burn_volume_raw": "0", + "recent_mints": [ + { + "tx_hash": "0x...", + "to": "0x...", + "amount_raw": "10000000000000000000000", + "block_number": 12345700, + "timestamp": "2026-06-20T14:22:00.000Z" + } + ], + "recent_burns": [], + "last_activity_at": "2026-06-20T14:22:00.000Z" + }, + "luca_read": "LUCA is a confirmed B20 asset linked to Luca via registry. 5 mint events detected, 0 burns. Issuer wallet is manifest-attributed. Financial books require separate EOA/treasury wallet declaration.", + "limitations": [ + "Token transfers are not operating revenue", + "Token contract is not an operator wallet", + "Issuer wallet (0x...) is not books-eligible unless declared in agent manifest", + "B20 activity is not included in Agent GDP", + "Holder concentration analysis requires a full transfer scan — not available in this endpoint" + ], + "data_integrity_warnings": [ + "gross_inflow_usd from token transfers ≠ operating revenue", + "Do not count B20 mint events as agent revenue", + "Token issuance is a financial event but not a revenue event" + ], + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## `linked_agent` — null case + +```json +{ + "linked_agent": null, + "manifest_status": "none", + "manifest_note": "No manifest found — B20 indexed, but financial books require wallet attribution" +} +``` + +## `manifest_status` values + +| Value | Meaning | +|-------|---------| +| `attributed` | Issuer wallet is manifest-declared with confirmed confidence | +| `candidate` | Issuer wallet is in a registry agent's wallet list but manifest not submitted | +| `none` | No agent link found | + +## `link_method` values + +| Value | Meaning | +|-------|---------| +| `known_token` | Token address declared in agent's registry entry | +| `manifest` | Linked via `.agent/wallets.json` | +| `erc8004` | Linked via ERC-8004 identity record | +| `admin` | Manually linked | +| `none` | No confirmed link | + +## Error responses + +| Status | Body | Cause | +|--------|------|-------| +| 400 | `{"error": "address must be a valid 0x Ethereum address"}` | Malformed address | +| 401 | `{"error": "Invalid API key."}` | Bad auth | +| 502 | `{"error": "B20 analysis failed"}` | Alchemy or DB lookup failed | diff --git a/skills/zetta/luca-report/SKILL.md b/skills/zetta/luca-report/SKILL.md new file mode 100644 index 0000000..2ad4a99 --- /dev/null +++ b/skills/zetta/luca-report/SKILL.md @@ -0,0 +1,125 @@ +# luca-report + +**Luca Skills by Zetta** — Callable financial intelligence for the agent economy. + +## What it does + +The single-call complete picture of an agent's financial identity. Combines registry identity, attribution tier, full financial statement, treasury balances, and a narrative summary into one response. This is the skill to use when you want everything about an agent in a single request. + +Internally it runs `agent-books` and treasury balance lookups in parallel, then assembles the composite. + +## Endpoint + +``` +POST https://www.zettaai.co/api/luca/skills/luca-report +``` + +## Auth + +``` +Authorization: Bearer zt_live_... +``` +or +``` +X-API-Key: zt_live_... +``` + +Get a key at [zettaai.co/developer](https://www.zettaai.co/developer). + +## Input + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `slug` | string | Yes | Agent slug (e.g. `"aeon"`) | +| `period` | string | No | One of: `7d`, `14d`, `30d`, `90d`. Default: `30d` | + +## Output + +```json +{ + "skill": "luca-report", + "agent": { + "name": "AEON", + "slug": "aeon", + "ecosystem": "AEON", + "verification_status": "verified", + "evidence_sources": ["manifest", "x_handle"], + "erc8004_agent_id": "0x...", + "erc8004_did": "did:ethr:base:0x...", + "website": "https://aeon.xyz", + "x_handle": "@aeon" + }, + "attribution": { + "tier": "manifest_attributed", + "books_eligible_wallets": 2, + "total_wallets": 5, + "source": "manifest" + }, + "books": { + "attributed": true, + "period": "30d", + "wallets": { "eligible": 2, "analyzed": 2, "total": 5 }, + "financials": { + "revenue_usd": 12450.00, + "expenses_usd": 3200.00, + "net_income_usd": 9250.00, + "gross_inflow_usd": 18000.00, + "margin_pct": 74.3, + "tx_count": 87 + }, + "confidence": "high" + }, + "treasury": { + "wallets": [ + { + "address": "0x...", + "label": "Treasury", + "role": "treasury", + "address_type": "treasury_contract", + "stable_balance_usd": 42500.00, + "chain": "base" + } + ], + "total_stable_balance_usd": 42500.00, + "health": "healthy" + }, + "summary": "AEON recorded $12,450.00 in operating revenue and $3,200.00 in expenses over 30d (87 transactions). Net income is positive at $9,250.00.", + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Output — agent not attributed + +When `attribution.tier` is `discovered` or `unattributed`: +- `books` will have `attributed: false` with a `reason` field +- `treasury.wallets` will be empty +- `summary` will be `null` + +## Integrity rules + +- ERC-8004 fields (`erc8004_agent_id`, `erc8004_did`) are identity only — they do not affect financial attribution +- `books` is null or unattributed unless the agent has manifest-declared `eoa` or `treasury_contract` wallets +- `treasury.wallets` includes only manifest-declared, books-eligible wallets — not all wallets in the registry +- Treasury health thresholds: `healthy` ≥ $10K, `low` ≥ $1K, `critical` < $1K, `unknown` = no manifest + +## Example + +```bash +curl -X POST https://www.zettaai.co/api/luca/skills/luca-report \ + -H "Authorization: Bearer zt_live_..." \ + -H "Content-Type: application/json" \ + -d '{"slug": "aeon", "period": "30d"}' +``` + +## Usage notes + +- This is the highest-latency skill — it runs books + treasury balance lookups in parallel. Typical response time: 1–3 seconds. +- `summary` is a data-derived narrative generated from financial figures — not a generative AI response +- For a breakdown of revenue quarantine logic, use `revenue-analysis` separately +- For per-wallet books-eligibility detail, use `registry-check` separately + +## Limitations + +- One agent per call +- Books and treasury are Base chain only +- `summary` is template-generated from financial data — not a Claude-written analysis diff --git a/skills/zetta/luca-report/references/api.md b/skills/zetta/luca-report/references/api.md new file mode 100644 index 0000000..376bd00 --- /dev/null +++ b/skills/zetta/luca-report/references/api.md @@ -0,0 +1,124 @@ +# Luca Report — API Reference + +## Request + +``` +POST https://www.zettaai.co/api/luca/skills/luca-report +Content-Type: application/json +Authorization: Bearer zt_live_... +``` + +### Body + +```json +{ + "slug": "aeon", + "period": "30d" +} +``` + +| Field | Type | Required | Validation | +|-------|------|----------|-----------| +| `slug` | string | Yes | Agent slug | +| `period` | string | No | One of: `7d`, `14d`, `30d`, `90d`. Default: `30d` | + +## Response — 200 OK + +```json +{ + "skill": "luca-report", + "agent": { + "name": "AEON", + "slug": "aeon", + "ecosystem": "AEON", + "verification_status": "verified", + "evidence_sources": ["manifest", "x_handle"], + "erc8004_agent_id": "0x...", + "erc8004_did": "did:ethr:base:0x...", + "website": "https://aeon.xyz", + "x_handle": "@aeon" + }, + "attribution": { + "tier": "manifest_attributed", + "books_eligible_wallets": 2, + "total_wallets": 5, + "source": "manifest" + }, + "books": { + "attributed": true, + "period": "30d", + "wallets": { "eligible": 2, "analyzed": 2, "total": 5 }, + "financials": { + "revenue_usd": 12450.00, + "expenses_usd": 3200.00, + "net_income_usd": 9250.00, + "gross_inflow_usd": 18000.00, + "margin_pct": 74.3, + "tx_count": 87 + }, + "confidence": "high", + "luca_summary": "AEON recorded $12,450.00 in operating revenue..." + }, + "treasury": { + "wallets": [ + { + "address": "0x...", + "label": "Treasury", + "role": "treasury", + "address_type": "treasury_contract", + "stable_balance_usd": 42500.00, + "chain": "base" + } + ], + "total_stable_balance_usd": 42500.00, + "health": "healthy" + }, + "summary": "AEON recorded $12,450.00 in operating revenue and $3,200.00 in expenses over 30d (87 transactions). Net income is positive at $9,250.00.", + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Unattributed response shape + +When `attribution.tier` is not `manifest_attributed`: + +```json +{ + "attribution": { + "tier": "unattributed", + "books_eligible_wallets": 0, + "total_wallets": 0, + "source": null + }, + "books": { + "attributed": false, + "reason": "No manifest-declared wallets found." + }, + "treasury": { + "wallets": [], + "total_stable_balance_usd": 0, + "health": "unknown" + }, + "summary": null +} +``` + +## Field notes + +| Field | Notes | +|-------|-------| +| `agent.erc8004_agent_id` | Identity only — not used for financial attribution | +| `agent.erc8004_did` | Identity only — not used for financial attribution | +| `attribution.source` | `"manifest"` when attributed, `null` otherwise | +| `treasury.health` | Based on manifest-eligible wallets only | +| `summary` | Template-generated from financial data, not a generative AI response | + +## Error responses + +| Status | Body | Cause | +|--------|------|-------| +| 400 | `{"error": "slug is required"}` | Missing slug | +| 400 | `{"error": "period must be 7d, 14d, 30d, or 90d"}` | Invalid period | +| 401 | `{"error": "Invalid API key."}` | Bad auth | +| 404 | `{"error": "Agent 'x' not found"}` | Not in registry | +| 500 | `{"error": "..."}` | Computation failed | diff --git a/skills/zetta/registry-check/SKILL.md b/skills/zetta/registry-check/SKILL.md new file mode 100644 index 0000000..15f56a7 --- /dev/null +++ b/skills/zetta/registry-check/SKILL.md @@ -0,0 +1,132 @@ +# registry-check + +**Luca Skills by Zetta** — Callable financial intelligence for the agent economy. + +## What it does + +Looks up an agent in the Zetta registry by slug, name fragment, or wallet address. Returns the agent's attribution tier, books-eligible wallet count, ERC-8004 identity if available, and the full wallet list with per-wallet eligibility status. + +Use this to check whether an agent is registered before running financial skills, or to find the correct slug when you only know a name or address. + +## Endpoint + +``` +POST https://www.zettaai.co/api/luca/skills/registry-check +``` + +## Auth + +``` +Authorization: Bearer zt_live_... +``` +or +``` +X-API-Key: zt_live_... +``` + +Get a key at [zettaai.co/developer](https://www.zettaai.co/developer). + +## Input + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `query` | string | Yes | Agent slug, name fragment, or 0x wallet address | + +Match priority: exact slug → exact wallet address → name substring. + +## Output — found + +```json +{ + "skill": "registry-check", + "found": true, + "query": "aeon", + "match_type": "slug", + "agent": { + "name": "AEON", + "slug": "aeon", + "ecosystem": "AEON", + "verification_status": "verified", + "evidence_sources": ["manifest", "x_handle"], + "erc8004_agent_id": "0x...", + "erc8004_did": "did:ethr:base:0x...", + "attribution_tier": "manifest_attributed", + "books_eligible_wallets": 2, + "total_wallets": 5, + "wallets": [ + { + "address": "0x...", + "label": "Treasury", + "role": "treasury", + "address_type": "treasury_contract", + "evidence_source": "manifest", + "books_eligible": true, + "books_ineligibility_reason": null, + "chain": "base" + }, + { + "address": "0x...", + "label": "Token", + "role": "token_contract", + "address_type": "token_contract", + "evidence_source": "manifest", + "books_eligible": false, + "books_ineligibility_reason": "address_type=token_contract is not books-eligible", + "chain": "base" + } + ] + }, + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Output — not found + +```json +{ + "skill": "registry-check", + "found": false, + "query": "unknownagent", + "agent": null, + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +### `attribution_tier` values + +| Value | Meaning | +|-------|---------| +| `manifest_attributed` | Has manifest-declared books-eligible wallets — books are running | +| `discovered` | Wallets in registry but none manifest-declared — books require manifest submission | +| `unattributed` | No wallets at all | + +### ERC-8004 fields + +`erc8004_agent_id` and `erc8004_did` are **identity fields only** — they are never used for financial attribution. An agent with an ERC-8004 identity still requires a manifest-declared `eoa` or `treasury_contract` wallet to produce financial books. + +## Example + +```bash +# By slug +curl -X POST https://www.zettaai.co/api/luca/skills/registry-check \ + -H "Authorization: Bearer zt_live_..." \ + -H "Content-Type: application/json" \ + -d '{"query": "aeon"}' + +# By wallet address +curl -X POST https://www.zettaai.co/api/luca/skills/registry-check \ + -H "Authorization: Bearer zt_live_..." \ + -H "Content-Type: application/json" \ + -d '{"query": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}' +``` + +## Usage notes + +- This is the recommended first call before `agent-books`, `treasury-monitor`, or `revenue-analysis` +- `found: false` means the agent is not in the Zetta registry — not that they have no wallets on-chain +- `match_type: "name"` uses substring match and may return the closest match, not an exact one + +## Limitations + +- Name matching is case-insensitive substring — not fuzzy. Typos will not resolve. +- Returns only the first match for name queries — if multiple agents share a name fragment, the result is the first alphabetically diff --git a/skills/zetta/registry-check/references/api.md b/skills/zetta/registry-check/references/api.md new file mode 100644 index 0000000..fd71f82 --- /dev/null +++ b/skills/zetta/registry-check/references/api.md @@ -0,0 +1,107 @@ +# Registry Check — API Reference + +## Request + +``` +POST https://www.zettaai.co/api/luca/skills/registry-check +Content-Type: application/json +Authorization: Bearer zt_live_... +``` + +### Body + +```json +{ "query": "aeon" } +``` + +| Field | Type | Required | Validation | +|-------|------|----------|-----------| +| `query` | string | Yes | Agent slug, name fragment, or 0x address | + +## Match priority + +1. Exact slug match (`"aeon"` → slug `aeon`) +2. Exact wallet address match (any wallet in the agent's wallet list) +3. Name substring match (case-insensitive) + +## Response — 200 OK (found) + +```json +{ + "skill": "registry-check", + "found": true, + "query": "aeon", + "match_type": "slug", + "agent": { + "name": "AEON", + "slug": "aeon", + "ecosystem": "AEON", + "verification_status": "verified", + "evidence_sources": ["manifest", "x_handle"], + "erc8004_agent_id": "0x...", + "erc8004_did": "did:ethr:base:0x...", + "attribution_tier": "manifest_attributed", + "books_eligible_wallets": 2, + "total_wallets": 5, + "wallets": [ + { + "address": "0x...", + "label": "Treasury", + "role": "treasury", + "address_type": "treasury_contract", + "evidence_source": "manifest", + "books_eligible": true, + "books_ineligibility_reason": null, + "chain": "base" + }, + { + "address": "0x...", + "label": "Token", + "role": "token_contract", + "address_type": "token_contract", + "evidence_source": "manifest", + "books_eligible": false, + "books_ineligibility_reason": "address_type=token_contract is not books-eligible", + "chain": "base" + } + ] + }, + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Response — 200 OK (not found) + +```json +{ + "skill": "registry-check", + "found": false, + "query": "unknownagent", + "agent": null, + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Attribution tiers + +| Tier | Meaning | +|------|---------| +| `manifest_attributed` | ≥ 1 manifest-declared, books-eligible wallet | +| `discovered` | Wallets in registry, none manifest-declared | +| `unattributed` | No wallets at all | + +## `match_type` values + +| Value | Meaning | +|-------|---------| +| `slug` | Matched on exact slug | +| `wallet_address` | Query was a 0x address found in the agent's wallet list | +| `name` | Matched on name substring | + +## Error responses + +| Status | Body | Cause | +|--------|------|-------| +| 400 | `{"error": "query is required (agent slug, name, or 0x wallet address)"}` | Empty query | +| 401 | `{"error": "Invalid API key."}` | Bad auth | +| 502 | `{"error": "Registry check failed"}` | DB lookup failed | diff --git a/skills/zetta/revenue-analysis/SKILL.md b/skills/zetta/revenue-analysis/SKILL.md new file mode 100644 index 0000000..c823275 --- /dev/null +++ b/skills/zetta/revenue-analysis/SKILL.md @@ -0,0 +1,112 @@ +# revenue-analysis + +**Luca Skills by Zetta** — Callable financial intelligence for the agent economy. + +## What it does + +Returns a detailed revenue breakdown for a registered agent, enforcing the critical distinction between gross inflows and operating revenue. Shows the quarantine breakdown, revenue recognition rate, expense categories, and per-source attribution. + +This skill exists specifically because gross inflows are not revenue. Any system that confuses the two produces inflated agent GDP figures. This skill surfaces the real number. + +## Endpoint + +``` +POST https://www.zettaai.co/api/luca/skills/revenue-analysis +``` + +## Auth + +``` +Authorization: Bearer zt_live_... +``` +or +``` +X-API-Key: zt_live_... +``` + +Get a key at [zettaai.co/developer](https://www.zettaai.co/developer). + +## Input + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `slug` | string | Yes | Agent slug (e.g. `"aeon"`) | +| `period` | string | No | One of: `7d`, `14d`, `30d`, `90d`. Default: `30d` | + +## Output — attributed + +```json +{ + "skill": "revenue-analysis", + "agent": { "name": "AEON", "slug": "aeon", "ecosystem": "AEON" }, + "period": "30d", + "attributed": true, + "wallets": { "eligible": 2, "analyzed": 2, "total": 5 }, + "revenue": { + "gross_inflow_usd": 18000.00, + "operating_revenue_usd": 12450.00, + "quarantined_inflows_usd": 5550.00, + "dex_excluded_usd": 800.00, + "revenue_recognition_rate_pct": 69, + "gross_inflow_is_not_revenue": true, + "note": "31% of gross inflows excluded (capital injections, DEX activity, or internal transfers)" + }, + "expenses": { + "total_usd": 3200.00, + "bridge_excluded_usd": 0.00, + "dex_excluded_usd": 800.00, + "net_income_usd": 9250.00, + "margin_pct": 74.3 + }, + "confidence": "high", + "breakdown": { + "revenue_by_source": [...], + "expenses_by_category": [...], + "quarantined_events": [...] + }, + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Output — unattributed + +```json +{ + "skill": "revenue-analysis", + "agent": { "name": "SomeAgent", "slug": "someagent" }, + "period": "30d", + "attributed": false, + "reason": "No manifest-declared wallets found." +} +``` + +## The gross inflow rule + +`gross_inflow_usd` and `operating_revenue_usd` are always different fields. They are **never** the same value unless all inflows are clean operating revenue (rare). The field `gross_inflow_is_not_revenue: true` is hardcoded in every attributed response as an explicit reminder. + +Inflows excluded from operating revenue: +- **Capital injections** — large one-off inflows from known investor/operator wallets +- **Internal transfers** — movement between the agent's own declared wallets +- **DEX receipts** — token swaps that inflate the raw inflow figure +- **Bridge receipts** — cross-chain transfers that are not operating income + +## Example + +```bash +curl -X POST https://www.zettaai.co/api/luca/skills/revenue-analysis \ + -H "Authorization: Bearer zt_live_..." \ + -H "Content-Type: application/json" \ + -d '{"slug": "aeon", "period": "30d"}' +``` + +## Usage notes + +- Always use `operating_revenue_usd`, not `gross_inflow_usd`, when reporting an agent's revenue +- `revenue_recognition_rate_pct` tells you what fraction of raw inflows are real operating revenue — a low rate (< 50%) means the agent has significant non-revenue inflows +- `quarantined_events` in the breakdown shows which specific transactions were excluded and why + +## Limitations + +- Quarantine classification is automated — edge cases may require manual review +- DEX exclusion covers common DEX routers on Base; novel or unrecognized DEX contracts may not be excluded +- Base chain only diff --git a/skills/zetta/revenue-analysis/references/api.md b/skills/zetta/revenue-analysis/references/api.md new file mode 100644 index 0000000..d6694eb --- /dev/null +++ b/skills/zetta/revenue-analysis/references/api.md @@ -0,0 +1,110 @@ +# Revenue Analysis — API Reference + +## Request + +``` +POST https://www.zettaai.co/api/luca/skills/revenue-analysis +Content-Type: application/json +Authorization: Bearer zt_live_... +``` + +### Body + +```json +{ + "slug": "aeon", + "period": "30d" +} +``` + +| Field | Type | Required | Validation | +|-------|------|----------|-----------| +| `slug` | string | Yes | Agent slug | +| `period` | string | No | One of: `7d`, `14d`, `30d`, `90d`. Default: `30d` | + +## Response — 200 OK (attributed) + +```json +{ + "skill": "revenue-analysis", + "agent": { "name": "AEON", "slug": "aeon", "ecosystem": "AEON" }, + "period": "30d", + "attributed": true, + "wallets": { "eligible": 2, "analyzed": 2, "total": 5 }, + "revenue": { + "gross_inflow_usd": 18000.00, + "operating_revenue_usd": 12450.00, + "quarantined_inflows_usd": 5550.00, + "dex_excluded_usd": 800.00, + "revenue_recognition_rate_pct": 69, + "gross_inflow_is_not_revenue": true, + "note": "31% of gross inflows excluded (capital injections, DEX activity, or internal transfers)" + }, + "expenses": { + "total_usd": 3200.00, + "bridge_excluded_usd": 0.00, + "dex_excluded_usd": 800.00, + "net_income_usd": 9250.00, + "margin_pct": 74.3 + }, + "confidence": "high", + "breakdown": { + "revenue_by_source": [ + { "source": "0x...", "label": "Inference payer", "amount_usd": 12450.00 } + ], + "expenses_by_category": [ + { "category": "inference", "amount_usd": 2100.00 }, + { "category": "gas", "amount_usd": 1100.00 } + ], + "quarantined_events": [ + { + "tx_hash": "0x...", + "amount_usd": 5000.00, + "reason": "capital_injection", + "timestamp": "2026-06-01T00:00:00.000Z" + } + ] + }, + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Response — 200 OK (unattributed) + +```json +{ + "skill": "revenue-analysis", + "agent": { "name": "SomeAgent", "slug": "someagent" }, + "period": "30d", + "attributed": false, + "reason": "No manifest-declared wallets found.", + "message": null +} +``` + +## Key fields + +| Field | Always use this | Never use this | +|-------|----------------|----------------| +| Revenue | `operating_revenue_usd` | `gross_inflow_usd` as revenue | +| Excluded | `quarantined_inflows_usd` shows what was removed | — | +| Integrity | `gross_inflow_is_not_revenue: true` hardcoded | — | + +## Quarantine reasons + +| Reason | Meaning | +|--------|---------| +| `capital_injection` | Large one-off inflow from known operator wallet | +| `internal_transfer` | Movement between the agent's own manifest wallets | +| `dex_receipt` | Token swap output — not operating income | +| `bridge_receipt` | Cross-chain bridge transfer | + +## Error responses + +| Status | Body | Cause | +|--------|------|-------| +| 400 | `{"error": "slug is required"}` | Missing slug | +| 400 | `{"error": "period must be 7d, 14d, 30d, or 90d"}` | Invalid period | +| 401 | `{"error": "Invalid API key."}` | Bad auth | +| 404 | `{"error": "Agent 'x' not found"}` | Not in registry | +| 500 | `{"error": "..."}` | Computation failed | diff --git a/skills/zetta/treasury-monitor/SKILL.md b/skills/zetta/treasury-monitor/SKILL.md new file mode 100644 index 0000000..cb0af68 --- /dev/null +++ b/skills/zetta/treasury-monitor/SKILL.md @@ -0,0 +1,129 @@ +# treasury-monitor + +**Luca Skills by Zetta** — Callable financial intelligence for the agent economy. + +## What it does + +Returns live stablecoin balances and a treasury health signal for an agent's declared wallets, or for a single address. Works with or without an agent slug — pass a wallet address directly for a quick balance check on any address. + +## Endpoint + +``` +POST https://www.zettaai.co/api/luca/skills/treasury-monitor +``` + +## Auth + +``` +Authorization: Bearer zt_live_... +``` +or +``` +X-API-Key: zt_live_... +``` + +Get a key at [zettaai.co/developer](https://www.zettaai.co/developer). + +## Input + +Pass either `slug` or `address`. At least one is required. + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `slug` | string | Conditional | Agent slug. Returns all manifest-declared wallets. | +| `address` | string | Conditional | Single 0x address. Returns one wallet row. | + +If both are provided, `slug` takes precedence. + +## Output — by slug + +```json +{ + "skill": "treasury-monitor", + "source": "slug", + "agent": { "name": "AEON", "slug": "aeon", "ecosystem": "AEON" }, + "wallets": [ + { + "address": "0x...", + "label": "Treasury", + "role": "treasury", + "address_type": "treasury_contract", + "evidence_source": "manifest", + "books_eligible": true, + "books_ineligibility_reason": null, + "stable_balance_usd": 42500.00, + "health": "healthy", + "chain": "base" + } + ], + "total_stable_balance_usd": 42500.00, + "health": "healthy", + "note": null, + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Output — by address + +```json +{ + "skill": "treasury-monitor", + "source": "address", + "agent": null, + "wallets": [ + { + "address": "0x...", + "address_type": "eoa", + "stable_balance_usd": 1200.00, + "health": "low", + "chain": "base" + } + ], + "total_stable_balance_usd": 1200.00, + "health": "low", + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +### Health signal + +| Signal | Threshold | +|--------|-----------| +| `healthy` | ≥ $10,000 USDC+USDT | +| `low` | ≥ $1,000, < $10,000 | +| `critical` | < $1,000 | +| `unknown` | No manifest wallets | + +## Integrity rules + +- Balance is USDC + USDT on Base only +- When called by slug: only manifest-declared, books-eligible wallets are shown by default. If no eligible wallets exist, all wallets are shown with a note +- `books_eligible: false` wallets are shown in the response but their balance does not count toward the agent's attributed treasury in books + +## Example + +```bash +# By agent slug +curl -X POST https://www.zettaai.co/api/luca/skills/treasury-monitor \ + -H "Authorization: Bearer zt_live_..." \ + -H "Content-Type: application/json" \ + -d '{"slug": "aeon"}' + +# By single address +curl -X POST https://www.zettaai.co/api/luca/skills/treasury-monitor \ + -H "Authorization: Bearer zt_live_..." \ + -H "Content-Type: application/json" \ + -d '{"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}' +``` + +## Usage notes + +- Balances are live — fetched from Alchemy at request time, not cached +- `health: "unknown"` means the agent has no manifest-declared wallets, not that the agent is insolvent +- Use this alongside `revenue-analysis` to calculate runway: `total_stable_balance_usd ÷ monthly_burn_rate` + +## Limitations + +- USDC and USDT on Base only — does not include ETH, WETH, or tokens +- No historical balance data — point-in-time only +- Base chain only diff --git a/skills/zetta/treasury-monitor/references/api.md b/skills/zetta/treasury-monitor/references/api.md new file mode 100644 index 0000000..fd890ec --- /dev/null +++ b/skills/zetta/treasury-monitor/references/api.md @@ -0,0 +1,110 @@ +# Treasury Monitor — API Reference + +## Request + +``` +POST https://www.zettaai.co/api/luca/skills/treasury-monitor +Content-Type: application/json +Authorization: Bearer zt_live_... +``` + +### Body — by slug + +```json +{ "slug": "aeon" } +``` + +### Body — by address + +```json +{ "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } +``` + +| Field | Type | Required | Validation | +|-------|------|----------|-----------| +| `slug` | string | Conditional | Agent slug. Required if `address` not provided. | +| `address` | string | Conditional | 0x address. Required if `slug` not provided. | + +## Response — 200 OK (by slug, with wallets) + +```json +{ + "skill": "treasury-monitor", + "source": "slug", + "agent": { "name": "AEON", "slug": "aeon", "ecosystem": "AEON" }, + "wallets": [ + { + "address": "0x...", + "label": "Treasury", + "role": "treasury", + "address_type": "treasury_contract", + "evidence_source": "manifest", + "books_eligible": true, + "books_ineligibility_reason": null, + "stable_balance_usd": 42500.00, + "health": "healthy", + "chain": "base" + } + ], + "total_stable_balance_usd": 42500.00, + "health": "healthy", + "note": null, + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Response — 200 OK (no manifest) + +```json +{ + "skill": "treasury-monitor", + "source": "slug", + "agent": { "name": "SomeAgent", "slug": "someagent", "ecosystem": null }, + "wallets": [], + "total_stable_balance_usd": 0, + "health": "unknown", + "note": "No wallets found for this agent. Submit a wallet manifest to enable treasury monitoring.", + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Response — 200 OK (by address) + +```json +{ + "skill": "treasury-monitor", + "source": "address", + "agent": null, + "wallets": [ + { + "address": "0x...", + "address_type": "eoa", + "stable_balance_usd": 1200.00, + "health": "low", + "chain": "base" + } + ], + "total_stable_balance_usd": 1200.00, + "health": "low", + "generated_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Health thresholds + +| Signal | Balance | +|--------|---------| +| `healthy` | ≥ $10,000 | +| `low` | ≥ $1,000, < $10,000 | +| `critical` | < $1,000 | +| `unknown` | No manifest wallets | + +## Error responses + +| Status | Body | Cause | +|--------|------|-------| +| 400 | `{"error": "slug or address is required"}` | Both missing | +| 400 | `{"error": "address must be a valid 0x Ethereum address"}` | Malformed address | +| 401 | `{"error": "Invalid API key."}` | Bad auth | +| 404 | `{"error": "Agent 'x' not found"}` | Slug not in registry | +| 502 | `{"error": "Treasury monitor failed"}` | Alchemy lookup failed | diff --git a/skills/zetta/wallet-audit/SKILL.md b/skills/zetta/wallet-audit/SKILL.md new file mode 100644 index 0000000..fa296c1 --- /dev/null +++ b/skills/zetta/wallet-audit/SKILL.md @@ -0,0 +1,92 @@ +# wallet-audit + +**Luca Skills by Zetta** — Callable financial intelligence for the agent economy. + +## What it does + +Classifies an on-chain address on Base and determines whether it is books-compatible for financial attribution. Returns the address type, books eligibility, and a stablecoin balance when the address is eligible. + +Use this before submitting a wallet to an agent manifest — it tells you whether that address type qualifies for financial books. + +## Endpoint + +``` +POST https://www.zettaai.co/api/luca/skills/wallet-audit +``` + +## Auth + +``` +Authorization: Bearer zt_live_... +``` +or +``` +X-API-Key: zt_live_... +``` + +Get a key at [zettaai.co/developer](https://www.zettaai.co/developer). + +## Input + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `address` | string | Yes | 0x Ethereum address to audit (42 chars) | +| `chain` | string | No | Chain name. Default: `"base"`. Only Base is supported. | + +## Output + +```json +{ + "skill": "wallet-audit", + "address": "0x...", + "chain": "base", + "address_type": "eoa", + "books_compatible": true, + "books_compatible_note": "This address type is eligible for books attribution when declared in the agent manifest", + "stable_balance_usd": 4250.00, + "notes": [ + "eoa wallets are books-compatible — declare this address in your agent manifest (evidenceSource: manifest) to enable financial attribution" + ], + "classified_at": "2026-06-23T00:00:00.000Z" +} +``` + +### `address_type` values + +| Value | Books-compatible | Description | +|-------|-----------------|-------------| +| `eoa` | Yes | Externally owned account | +| `treasury_contract` | Yes | Gnosis Safe or equivalent multisig | +| `token_contract` | **No** | ERC-20 / ERC-721 / ERC-1155 | +| `smart_contract` | **No** | General smart contract | +| `proxy_contract` | **No** | Upgradeable proxy | +| `vault` | **No** | DeFi vault | +| `unknown` | **No** | Unclassifiable | + +## Integrity rules + +- Discovered wallets are not automatically books-eligible — they must be declared in `.agent/wallets.json` +- Token contracts are excluded regardless of manifest declaration +- Smart contracts and proxy contracts are not books-eligible even if declared +- Only `eoa` and `treasury_contract` types produce attributed financial books + +## Example + +```bash +curl -X POST https://www.zettaai.co/api/luca/skills/wallet-audit \ + -H "Authorization: Bearer zt_live_..." \ + -H "Content-Type: application/json" \ + -d '{"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}' +``` + +## Usage notes + +- `stable_balance_usd` is only populated when `books_compatible: true` +- Use this skill before running `agent-books` to confirm a wallet will produce attributed books +- A `true` result here means the address *type* qualifies — the wallet must also be manifest-declared for books to run + +## Limitations + +- Base chain only +- Does not verify whether the wallet is already in a manifest — use `registry-check` for that +- Balance is USDC + USDT on Base only; ETH and other assets are not included in the balance figure diff --git a/skills/zetta/wallet-audit/references/api.md b/skills/zetta/wallet-audit/references/api.md new file mode 100644 index 0000000..51a5cb5 --- /dev/null +++ b/skills/zetta/wallet-audit/references/api.md @@ -0,0 +1,80 @@ +# Wallet Audit — API Reference + +## Request + +``` +POST https://www.zettaai.co/api/luca/skills/wallet-audit +Content-Type: application/json +Authorization: Bearer zt_live_... +``` + +### Body + +```json +{ + "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", + "chain": "base" +} +``` + +| Field | Type | Required | Validation | +|-------|------|----------|-----------| +| `address` | string | Yes | Must match `/^0x[0-9a-fA-F]{40}$/` | +| `chain` | string | No | Default: `"base"`. Only `"base"` is supported. | + +## Response — 200 OK + +```json +{ + "skill": "wallet-audit", + "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045", + "chain": "base", + "address_type": "eoa", + "books_compatible": true, + "books_compatible_note": "This address type is eligible for books attribution when declared in the agent manifest", + "stable_balance_usd": 4250.00, + "notes": [ + "eoa wallets are books-compatible — declare this address in your agent manifest (evidenceSource: manifest) to enable financial attribution" + ], + "classified_at": "2026-06-23T00:00:00.000Z" +} +``` + +### `books_compatible: false` example + +```json +{ + "skill": "wallet-audit", + "address": "0xb2b335f832fd3f43461ebd1cd9831d93d9ca4ba3", + "chain": "base", + "address_type": "token_contract", + "books_compatible": false, + "books_compatible_note": "This address type is excluded from books regardless of manifest declaration", + "stable_balance_usd": null, + "notes": [ + "token_contract wallets are excluded from books regardless of manifest declaration", + "Token contracts are excluded to prevent inflating revenue figures with token issuance events" + ], + "classified_at": "2026-06-23T00:00:00.000Z" +} +``` + +## Error responses + +| Status | Body | Cause | +|--------|------|-------| +| 400 | `{"error": "address must be a valid 0x Ethereum address (42 chars)"}` | Malformed address | +| 401 | `{"error": "Missing API key. Pass it as Authorization: Bearer or X-API-Key header."}` | No auth | +| 401 | `{"error": "Invalid API key."}` | Bad key | +| 429 | `{"error": "Rate limit reached (100 requests/day). Resets at midnight UTC. Hold ≥1,000 $LUCA..."}` | Rate limit | +| 502 | `{"error": "Address classification failed"}` | Alchemy lookup failed | + +## Rate limits + +| Tier | Requirement | Requests/day | +|------|-------------|--------------| +| Free | Any key | 100 | +| Developer | ≥ 1,000 $LUCA | 500 | +| Enterprise | ≥ 10,000 $LUCA | 2,000 | + +Resets midnight UTC. Link your wallet at [zettaai.co/developer](https://www.zettaai.co/developer) to upgrade.