Skill: alexgrankinukr-hash/k3-blockchain-agent (version 1.0.0)

--- name: k3-blockchain-agent description: > Build automated blockchain analysis workflows on K3 — from natural language requests to deployed, running automations that fetch on-chain data, analyze it with AI, and deliver insights via email, Telegram, or Slack. Use this skill whenever the user mentions blockchain workflows, on-chain analytics, DeFi monitoring, token tracking, wallet alerts, pool analysis, protocol dashboards, NFT tracking, automated trading, smart contract monitoring, or wants to automate anything involving blockchain data. Also trigger when the user mentions K3, workflow builder, or wants scheduled crypto/DeFi reports. Even if they just say "monitor this wallet" or "track this token" — this skill applies. --- # K3 Blockchain Agent Transform requests like *"Send me daily updates about the WETH/USDC pool on Uniswap"* into fully deployed workflows that fetch data, run AI analysis, and deliver reports automatically. ## Setup This skill requires the **K3 Development MCP** to be connected. The MCP provides tools like `generateWorkflow`, `executeWorkflow`, `findAgentByFunctionality`, and others that let you create and manage blockchain workflows programmatically. If the K3 MCP isn't connected yet, tell the user they need to add it before proceeding. Once connected, verify by calling `listTeamMcpServerIntegrations()` — this confirms the connection and shows what data source integrations (TheGraph, CoinGecko, etc.) the user's team has wired up. Every team's integrations will be different — discover what's available rather than assuming. ## How Workflow Building Works The K3 orchestrator is **conversational**. You describe what you want in plain language, and the orchestrator asks clarifying questions, then builds and deploys the workflow. Your job is to show up with the right information so the conversation is productive. The loop: ``` UNDERSTAND → what does the user actually want? FIND DATA → how do we get that information into the workflow? TEST → does the data actually come back correctly? BUILD → give the orchestrator everything it needs DEPLOY → launch it and verify it works ``` Skipping "test" is the most common mistake — you end up with a deployed workflow that returns empty data. ## Step 1: Understand the Request When a user asks for a workflow, figure out these parameters. Ask if anything is unclear — don't guess on addresses or emails. | Parameter | What to find out | Examples | |-----------|-----------------|----------| | **Data target** | What blockchain data do they need? | pool metrics, token price, wallet balance, NFT data | | **Protocol** | Which DeFi protocol or chain feature? | Uniswap, Aave, SushiSwap, native transfers | | **Chain** | Which blockchain? | Ethereum, Arbitrum, Polygon, Base, Stellar | | **Schedule** | How often / what triggers it? | daily, hourly, on-demand, on wallet activity, on contract event, Telegram chatbot | | **Analysis** | What kind of insights? | performance summary, anomaly alerts, trend report, trade signal | | **Delivery** | How should results arrive? | email, Telegram, Slack, Google Sheets | | **Actions** | Should the workflow do anything? | execute a swap, transfer tokens, write to a contract | | **Specifics** | Any addresses or IDs? | pool address, token contract, wallet address | If the user is new to DeFi, briefly explain relevant concepts as you go (what TVL means, what a liquidity pool is, etc.). Don't assume they know the jargon. ## Step 2: Find the Right Data This is the critical step. K3 has many ways to get data into a workflow, and you need to figure out which approach works for the user's specific request. ### K3 data functions These are the built-in functions for getting data into a workflow. Read `references/node-types.md` for full details on each. | Function | What it does | |----------|-------------| | **Read API** | Call any REST/GraphQL API — the most flexible option | | **Read Smart Contract** | Query any smart contract directly on-chain | | **Read Market Data** | Get token prices, volumes, market metrics | | **Read Wallet** | Wallet balances, transfers, transaction history | | **Read NFT** | NFT collections, floor prices, traits, holders | | **Read Graph** | Query TheGraph subgraphs with custom GraphQL | | **Read Deployment** | Pull output from your own deployed code on K3 | | **AI Web Scraper** | Extract structured data from any web page | | **AI Agent with tools** | AI that dynamically decides what to fetch | ### How to find the data you need The goal is to figure out the best way to get the specific data the user wants. Think of it as problem-solving — there are multiple valid approaches and you should explore them: 1. **Check what the team already has** — call `listTeamMcpServerIntegrations()` to see what MCP data sources are connected. If they have TheGraph, CoinGecko, or other integrations set up, those are the easiest path. 2. **Search for existing templates** — call `findAgentByFunctionality()` with the user's intent. If someone already built a similar workflow, use it as a starting point. 3. **Think about which K3 function fits**: - Need on-chain contract data? → **Read Smart Contract** can query it directly - Need token prices or market data? → **Read Market Data** has it built in - Need complex DeFi metrics (TVL, volume, fees)? → **Read Graph** with the right subgraph, or **Read API** to a protocol's analytics endpoint - Need wallet info? → **Read Wallet** for balances and history - Need NFT data? → **Read NFT** for collections and metadata - Need data from any public API? → **Read API** can call anything - Need to scrape a website? → **AI Web Scraper** can extract and structure it 4. **Search the web** for the right endpoint. If you need a specific protocol's data, look up `{protocol name} API`, `{protocol name} subgraph`, or `{protocol name} GraphQL endpoint`. Many protocols publish public APIs and subgraphs. 5. **Ask the user** — they may know the API endpoint, have an API key, or know exactly which smart contract to read from. The key insight: there's rarely just one way to get the data. A Uniswap pool's TVL could come from Read Graph (subgraph query), Read API (calling an analytics endpoint), or even Read Smart Contract (reading the pool contract directly). Pick whichever is most reliable and gives you the data format you need. ### Test before you build Before constructing the full workflow, verify the data source actually returns what you expect: ``` 1. Create a minimal test workflow with generateWorkflow() — just a trigger + one data fetch step, nothing else 2. Deploy and run it with executeWorkflow() 3. Check the output with getWorkflowRunById() (set includeWorkflowData: true) 4. If the data looks right → proceed to full build 5. If empty or wrong → try a different approach and test again ``` This saves a lot of debugging later. A deployed workflow with bad data is worse than no workflow. ## Step 3: Build the Workflow Now give the K3 orchestrator everything it needs. Use `generateWorkflow()` with a detailed prompt that includes: - **Trigger type and schedule** (e.g., "runs daily" or "triggers on wallet activity") - **Data source and how to query it** (e.g., "use Read Graph to query pool X" or "use Read Smart Contract to get the pair's reserves") - **What the AI should analyze** (e.g., "highlight TVL changes over 5%") - **Any actions to take** (e.g., "execute a swap on Uniswap if condition is met") - **How to deliver results** (e.g., "send Telegram alert" or "email the report") - **Any MCP integration IDs** the orchestrator needs (from team integrations) Set `deployWorkflow: false` on the first call so you can review before deploying. The orchestrator will likely ask follow-up questions — answer them using `editGeneratedWorkflow()` with the same `generatedWorkflowId`. This back-and-forth is normal; expect 2-4 rounds. Once the configuration looks correct, call `editGeneratedWorkflow()` one final time with `deployWorkflow: true`. For the full list of available functions, triggers, AI models, and output options, read `references/node-types.md`. ## Step 4: Deploy and Verify After deploying: 1. **Run it manually** with `executeWorkflow()` to trigger an immediate test 2. **Check the run** with `getWorkflowRuns()` or `getWorkflowRunById()` 3. **Verify the full chain**: Did data fetch? Did AI analyze? Did notification send? If something failed, use `editGeneratedWorkflow()` to fix it — you don't need to start over. See `references/troubleshooting.md` for common issues. Tell the user what happened: "Your workflow is live and will run daily. I just ran a test — here's what the first report looks like: [summary]." ## K3 MCP Tool Reference | Tool | What it does | |------|-------------| | `generateWorkflow` | Start building a workflow from natural language | | `editGeneratedWorkflow` | Continue the conversation with the orchestrator | | `executeWorkflow` | Run a workflow manually | | `getWorkflowById` | Get workflow details and config | | `getWorkflowRuns` | List execution history | | `getWorkflowRunById` | Get a specific run's details and output | | `updateWorkflow` | Pause/unpause a scheduled workflow | | `findAgentByFunctionality` | Search for existing workflow templates | | `listAgentTemplates` | Browse all available templates | | `getAgentTemplateById` | Get details on a specific template | | `listTeamMcpServerIntegrations` | See what data sources the team has connected | | `listMcpServerIntegrations` | Browse all available MCP data sources | ## Important Rules 1. **Always test data sources** before building the full workflow. A quick test fetch saves a lot of debugging time. 2. **The orchestrator is conversational** — expect multiple rounds of back-and-forth via `editGeneratedWorkflow`. That's how it's designed to work. 3. **Ask the user for anything you can't look up** — never guess email addresses, Telegram handles, or wallet addresses. 4. **Discover team integrations** — call `listTeamMcpServerIntegrations()` to see what's available. Every team is different. 5. **Verify workflows work** before telling the user it's done. Run it, check the output, confirm delivery. 6. **Be mindful of context** — don't call many K3 MCP tools at once or dump large responses. Fetch what you need, check it, move on. 7. **Use web search** to find API endpoints, subgraph URLs, and smart contract addresses when you don't know them. The web is your research tool. ## Going Deeper - `references/node-types.md` — All trigger types, data functions, AI functions, DeFi/trading actions, and notification options - `references/data-sources.md` — How to discover and evaluate data sources for different blockchain data needs - `references/workflow-patterns.md` — Common workflow architectures and when to use each one - `references/troubleshooting.md` — Diagnosing and fixing common workflow issues

path: references/data-sources.md
content: # Data Sources — Discovery Guide

This file helps you figure out how to get specific blockchain data into a K3
workflow. Rather than a fixed lookup table, think of this as a problem-solving
guide — there are multiple valid approaches for most data needs, and you should
explore to find what works best.

## Table of Contents

1. [Discovery Process](#discovery-process)
2. [Common Data Needs and Approaches](#common-data-needs-and-approaches)
3. [Finding Endpoints Online](#finding-endpoints-online)
4. [Well-Known Public APIs](#well-known-public-apis)

---

## Discovery Process

Every team's K3 setup is different. Before assuming how to get data:

### 1. Check team MCP integrations

Call `listTeamMcpServerIntegrations()` to see what the team has connected. Common
integrations include TheGraph, CoinGecko, and various protocol-specific MCPs. If
an integration exists for your data need, use it — it's already set up and working.

### 2. Search for existing templates

Call `findAgentByFunctionality()` describing what you need. If someone already
built a workflow for a similar purpose, you can use it directly or learn from its
data source approach.

### 3. Browse available MCP servers

Call `listMcpServerIntegrations()` to see all MCP servers available in the K3
ecosystem. There may be a ready-made integration that the team hasn't connected yet.

### 4. Research online

Search the web for `{protocol name} API` or `{protocol name} subgraph` to find
public endpoints. Most serious DeFi protocols publish APIs and documentation.

### 5. Ask the user

They may know the endpoint, have an API key, or have a specific smart contract
they want to read from.

---

## Common Data Needs and Approaches

These are directional suggestions — not rules. The best approach depends on what
the team has connected and what data format you need.

### Token prices and market data

**Easiest**: Read Market Data (built-in, no configuration needed)
**Also works**: Read API → CoinGecko, CoinMarketCap, or other market data APIs
**Via MCP**: If the team has CoinGecko or Token API MCP connected

### DEX pool metrics (TVL, volume, fees)

**Common approach**: Read Graph → query the protocol's TheGraph subgraph
**Also works**: Read API → protocol's analytics REST endpoint (e.g., Uniswap has
various analytics APIs), Read Smart Contract → read the pool contract directly
**Via MCP**: If the team has TheGraph Subgraph MCP connected

### Wallet balances and holdings

**Easiest**: Read Wallet (built-in, pass wallet address and chain)
**Also works**: Read Smart Contract → call `balanceOf` on individual tokens
**Via MCP**: Various wallet data MCPs may be available

### Smart contract state

**Direct approach**: Read Smart Contract → call any public function on the contract
**Also works**: Read Graph if the data is indexed by a subgraph
**Good for**: Interest rates, reserves, governance parameters, pool configurations

### NFT data (collections, floor prices, traits)

**Easiest**: Read NFT (built-in)
**Also works**: Read API → OpenSea, Reservoir, or other NFT APIs

### Historical on-chain data

**Common approach**: Read Graph → query historical entities (dayData, hourData)
**Also works**: Read API → analytics APIs that serve historical data
**Via AI Agent**: Use Web3 Data Fetcher tool to let AI query historical prices

### Cross-protocol or cross-chain comparisons

**Approach**: Multiple Read nodes → one for each protocol/chain → feed all into
an AI node for comparative analysis
**Also works**: AI Agent with tools enabled → let the AI decide what to fetch

### Data from websites without APIs

**Approach**: AI Web Scraper → point it at the page and describe what to extract

---

## Finding Endpoints Online

When you need a specific protocol's data and don't know the endpoint:

1. **TheGraph Explorer** — search for `{protocol name}` subgraphs. Many protocols
   publish subgraphs even if they're not well-known. Different chains have
   different deployments.

2. **Protocol documentation** — check their docs site for "API", "Developers", or
   "Integration" sections. Most serious protocols publish REST or GraphQL endpoints.

3. **Protocol frontend inspection** — open their analytics/info page, use browser
   DevTools → Network tab, filter by "graphql" or "fetch". The URLs and payloads
   show you exactly what data is available.

4. **DeFiLlama** — `api.llama.fi` provides REST endpoints for TVL, yields, and
   protocol metrics across hundreds of protocols. Good fallback when protocol-specific
   APIs are hard to find.

5. **Block explorers** — Etherscan, Arbiscan, Polygonscan etc. can help you find
   contract addresses and verify which functions are available on a smart contract
   (useful for Read Smart Contract approach).

---

## Well-Known Public APIs

These are commonly used and well-documented. Not exhaustive — search the web for
more options.

| API | What it provides | Endpoint style |
|-----|-----------------|----------------|
| CoinGecko | Token prices, volume, market cap, trending | REST |
| DeFiLlama | TVL, yields, protocol metrics across many protocols | REST |
| TheGraph | DEX data, DeFi metrics via protocol-specific subgraphs | GraphQL |
| Etherscan / chain explorers | Transaction data, contract verification, token transfers | REST |
| OpenSea / Reservoir | NFT sales, floor prices, collection data | REST |
| Alchemy / Infura | Raw blockchain data, token balances, logs | REST / JSON-RPC |

Remember: Read API can call any of these. Read Smart Contract can bypass APIs
entirely and query the blockchain directly. The best approach depends on what data
you need and what format is most useful for the workflow.


path: references/troubleshooting.md
content: # Troubleshooting

When a workflow doesn't work as expected, use this guide to diagnose and fix the
issue. Start by checking the workflow run output with `getWorkflowRunById()` —
it usually tells you what went wrong.

---

## Data is empty or wrong

**Symptoms**: Workflow runs successfully but the data step returns null, empty
arrays, or unexpected values.

**Diagnose**:
1. Check `getWorkflowRunById({ workflowRunId, includeWorkflowData: true })` to see
   exactly what each node returned
2. Look at the data fetch node's output specifically

**Common causes and fixes**:

- **Wrong API endpoint or subgraph URL**: Verify the URL is correct. Subgraph URLs
  are chain-specific — the Uniswap V3 Ethereum subgraph is different from Arbitrum.
  Search the web for the correct URL.

- **Wrong pool/token address**: Addresses are chain-specific. The WETH/USDC pool on
  Ethereum has a different address than on Arbitrum. Verify with the protocol's UI
  or a block explorer.

- **Subgraph query returns wrong fields**: TheGraph subgraph schemas vary. Check
  what entities and fields are available by looking at the subgraph's schema. The
  orchestrator may have guessed wrong field names.

- **API requires authentication**: Some endpoints need an API key in headers. Check
  the API docs and add credentials if needed.

- **Rate limiting**: If the API returns 429 errors, you're hitting rate limits.
  Reduce frequency or add an API key for higher limits.

**Fix approach**: Create a minimal test workflow that only does the data fetch. Run
it, inspect the raw output. Fix the query/URL, test again. Once data looks right,
update the full workflow with `editGeneratedWorkflow()`.

---

## AI analysis is not useful

**Symptoms**: The AI node runs but the output is generic, doesn't reference the
actual data, or misses the point.

**Common causes and fixes**:

- **Prompt is too vague**: Instead of "analyze this data", write "analyze the pool's
  TVL change over 24 hours, flag any changes over 5%, compare volume to 7-day
  average, and note any unusual fee activity."

- **Data isn't structured**: If the AI receives a wall of text instead of JSON, it
  struggles. Make sure the data fetch returns structured data that the AI can parse.

- **Wrong model**: `gemini-2.5-flash` is good for most tasks but may struggle with
  complex multi-step analysis. Try a different model if the analysis quality is poor.

- **No output format specified**: Tell the AI exactly how to structure its response
  — sections, headings, what to include in each section.

**Fix approach**: Edit the AI node's prompt via `editGeneratedWorkflow()`. Be
specific about what to analyze, what to highlight, and how to format the output.
Include examples of the desired output if possible.

---

## Notification didn't arrive

**Symptoms**: Workflow ran, data looks good, AI analysis looks good, but the email
or Telegram message never arrived.

**Common causes and fixes**:

- **Email MCP not connected**: Check `listTeamMcpServerIntegrations()` to verify the
  Email (Composio) integration is active.

- **Wrong email address**: Verify the recipient email is correct in the workflow
  config. Typos happen.

- **Check spam folder**: AI-generated emails sometimes land in spam.

- **Telegram bot not configured**: If using WriteAPI to a Telegram bot, verify the
  bot token and chat ID are correct. The chat ID must be for the specific
  conversation where the bot should post.

- **WriteAPI endpoint is wrong**: If using a webhook, verify the URL is correct and
  the service is accepting requests.

---

## Scheduled workflow isn't running

**Symptoms**: You deployed a scheduled workflow but it never executes.

**Diagnose**:
1. `getWorkflowById()` — check if the workflow is paused
2. `getWorkflowRuns()` — check if there are any runs at all, or runs with errors

**Common causes and fixes**:

- **Workflow is paused**: Use `updateWorkflow()` to unpause it.

- **Trigger misconfigured**: The schedule interval might be wrong. Check the trigger
  node's config in the workflow details.

- **Workflow errored on first run and stopped**: Some errors can halt the schedule.
  Fix the error and re-enable.

---

## Orchestrator isn't building what I described

**Symptoms**: The `generateWorkflow` or `editGeneratedWorkflow` output doesn't match
what you asked for.

**Fixes**:

- **Be more specific**: Instead of "fetch pool data", say "use TheGraph Subgraph MCP
  (integration ID: ca0072f7-...) to query Uniswap V3 subgraph on Ethereum for pool
  0x8ad599... and get totalValueLockedUSD, volumeUSD, and feesUSD from poolDayDatas"

- **Break it into steps**: If your prompt asks for too much at once, the orchestrator
  may miss details. Start simple, then add complexity via `editGeneratedWorkflow`.

- **Provide the MCP integration ID**: Don't assume the orchestrator knows which
  integration to use. Give it the specific ID from
  `listTeamMcpServerIntegrations()`.

- **Iterate**: Remember the orchestrator is conversational. If the first attempt
  isn't right, explain what's wrong and what you want changed. 2-4 rounds is normal.


path: references/workflow-patterns.md
content: # Workflow Patterns

These are common workflow architectures on K3. When a user describes what they want,
match their request to one of these patterns and use it as the blueprint.

---

## Pattern 1: Daily Digest

The most common pattern. Fetches data on a schedule, runs AI analysis, delivers
a report.

```
[Scheduled] → [Read data] → [AI analysis] → [Email / Telegram / Slack]
```

**When to use**: "Send me daily updates about...", "I want a morning report on...",
"Track this pool and email me every day"

**Example prompt to orchestrator**: "Create a workflow that runs daily, uses Read
Graph to query the Uniswap V3 subgraph for pool metrics, then uses AI Service to
summarize performance and highlight notable changes, then sends the report via email."

**Key decisions**: What schedule? What data points? What should the AI highlight?
Where to deliver?

---

## Pattern 2: On-Demand Report

User triggers manually and optionally provides parameters. Good for ad-hoc analysis.

```
[On-Demand] → [Custom Input] → [Read data] → [AI analysis] → [Return / Email]
```

**When to use**: "Let me analyze any token on demand", "Build me a tool I can query",
"I want to check this whenever I want"

**Example**: User enters a token name → Read Market Data gets the price/volume →
AI generates an analysis → result returned or emailed.

**Key decisions**: What parameters does the user provide? How flexible should the
analysis be?

---

## Pattern 3: Wallet Monitor

Reacts to wallet activity in real time. Triggers when a specific address does
something, enriches with context, sends alert.

```
[Wallet Event] → [Read Wallet / Read API] → [AI analysis] → [Telegram / Email]
```

**When to use**: "Notify me when this wallet moves", "Watch this whale", "Alert me
on transfers from address X"

**Example**: Whale wallet triggers activity → Read Wallet gets current portfolio →
AI assesses significance → Telegram alert with summary.

**Key decisions**: Which address(es)? What counts as interesting? How fast does the
alert need to be?

---

## Pattern 4: Smart Contract Event Reactor

Listens for specific events emitted by a smart contract. More targeted than wallet
monitoring — watches a contract, not a wallet.

```
[Smart Contract Event] → [Read data for context] → [AI assess] → [Alert / Action]
```

**When to use**: "Alert me on large swaps", "Notify on Aave liquidations", "Watch
for governance proposals", "Trigger an action when a specific event happens"

**Example**: Pool contract emits Swap event → Read Market Data gets token prices for
USD conversion → AI checks if over threshold → Telegram alert.

**Key decisions**: Which contract and event? What threshold or filter? How much
context enrichment?

---

## Pattern 5: Multi-Source Comparison

Pulls from multiple data sources, feeds into AI for comparative analysis.

```
[Scheduled] → [Read source 1] → [Read source 2] → [AI compare] → [Report]
```

**When to use**: "Compare pools across DEXes", "Best yield across protocols",
"How does this token perform on different chains?"

**Example**: Read Graph → Uniswap V3 pool + Read Graph → SushiSwap pool → AI
compares TVL, volume, fees, makes recommendation.

**Key decisions**: Which sources to compare? What metrics? Should the AI recommend?

---

## Pattern 6: AI-Driven Research

Uses AI Agent with tools to dynamically research a topic. The AI decides what to
fetch based on the question.

```
[On-Demand / Scheduled] → [AI Agent with tools] → [Format / Deliver]
```

**When to use**: "Research this protocol for me", "What's happening in DeFi today?",
"Give me a comprehensive analysis" — where the data needs aren't predefined.

**Example**: AI Agent with Web3 Data Fetcher and MCP tools enabled → user asks a
question → AI decides what data to look up, fetches it, and synthesizes a report.

**Key decisions**: Which tools should the AI have access to? How broad should it go?
What's the output format?

---

## Pattern 7: Automated Trading / Action

Analyzes data and then takes an on-chain action based on the analysis.

```
[Scheduled / Event] → [Read data] → [AI Conditional] → [Uniswap / Token Transfer / Write Smart Contract]
```

**When to use**: "Swap when price hits X", "Rebalance my portfolio weekly",
"Auto-transfer tokens when conditions are met"

**Example**: Scheduled check → Read Market Data for token price → AI Conditional
checks if below target → Uniswap swap executes.

**Key decisions**: What conditions trigger the action? How much should the AI decide
vs. hard rules? What safeguards (spending limits, confirmation)?

**Important**: This pattern involves real money. Make sure the user understands
exactly what actions the workflow will take and under what conditions.

---

## Pattern 8: Data Collection & Storage

Collects data over time and stores it for historical analysis or dashboards.

```
[Scheduled] → [Read data] → [Write API / Google Sheets / S3]
```

**When to use**: "Track this metric over time", "Build a dataset of pool performance",
"Store daily snapshots for analysis later"

**Example**: Daily schedule → Read Graph for pool TVL → Write to Google Sheets with
timestamp → accumulates a historical dataset.

**Key decisions**: What data to collect? Where to store? How to handle schema over
time?

---

## Pattern 9: Web Scraping Pipeline

Extracts data from websites, processes it with AI, delivers insights.

```
[Scheduled] → [AI Web Scraper] → [AI analysis] → [Notification]
```

**When to use**: "Monitor this protocol's blog for updates", "Track governance
forum discussions", "Extract data from a site that doesn't have an API"

**Example**: AI Web Scraper pulls latest posts from a governance forum → AI
summarizes new proposals → Slack notification to the team.

**Key decisions**: Which pages to scrape? How often? What to extract vs. summarize?

---

## Pattern 10: Multi-Step Pipeline with Enrichment

Chains multiple data reads and AI steps for complex analysis.

```
[Trigger] → [Read A] → [AI process A] → [Read B based on A's output] → [AI final] → [Deliver]
```

**When to use**: Complex analyses where later steps depend on earlier results.
"Find the top-performing pools, then deep-dive into each one."

**Example**: Read Graph gets top 10 pools by volume → AI picks the most interesting
3 → Read Smart Contract gets detailed state for each → AI writes a deep analysis →
Email report.

**Key decisions**: How to chain the logic? What does each step pass to the next?
How to handle the case where intermediate data is unexpected?

---

## Pattern 11: Telegram Chatbot Agent

Connects a Telegram bot to an AI-powered workflow so users can interact with
blockchain data conversationally — just send the bot a message and get back
intelligent responses.

```
[Telegram Chatbot trigger] → [AI Agent with tools/MCP] → [Telegram reply]
```

**When to use**: "I want to chat with an AI about crypto on Telegram", "Build me
a Telegram bot that can check wallet balances", "I want on-chain data at my
fingertips in a chat"

**Example 1 — Wallet analyzer bot**: User sends a wallet address to the Telegram
bot → AI Agent receives the message → uses Read Wallet to get balances and
holdings → analyzes the portfolio → replies in Telegram with a summary.

**Example 2 — Market data assistant**: User asks "what's happening with ETH?" →
AI Agent with CoinGecko MCP fetches price, volume, and trends → generates a
concise market update → replies in the chat.

**Example 3 — DeFi research bot**: User sends "analyze the top Uniswap pools" →
AI Agent with Read Graph tool queries the subgraph → picks interesting pools →
replies with key metrics and insights.

**Key decisions**: What tools/MCPs should the AI Agent have access to? How
conversational vs. structured should the responses be? Should the bot support
follow-up questions or treat each message independently?

**Design tip**: The Telegram chatbot trigger passes the user's message as input
to the workflow. An AI Agent node is the natural fit here because it can interpret
the user's intent, decide which tools to call, and compose a natural response —
all in one step. Connect relevant MCP tools (CoinGecko, TheGraph, etc.) to give
the AI Agent access to the data it needs.

---

## Combining Patterns

Real workflows often combine elements from multiple patterns. A daily digest
might include wallet monitoring logic, or an automated trading workflow might
include a notification step. Use these patterns as starting points, then mix and
match based on what the user actually needs.


path: references/node-types.md
content: # K3 Node Types Reference

Every K3 workflow is a chain of nodes. This file describes all available node types
so you know what's possible when designing a workflow.

## Table of Contents

1. [Triggers](#triggers)
2. [Read Functions (Data Input)](#read-functions-data-input)
3. [AI Functions](#ai-functions)
4. [Write Functions (Output & Actions)](#write-functions-output--actions)
5. [DeFi & Trading Functions](#defi--trading-functions)
6. [Notification Functions](#notification-functions)
7. [Utility Functions](#utility-functions)

---

## Triggers

Every workflow has exactly one trigger that determines when it starts.

### Scheduled / Manual

Runs on a repeating time interval, or manually on demand.

When to use: Daily digests, hourly monitors, periodic reports, or workflows you
want to trigger manually or via API.

Config: Choose frequency (hourly, daily, etc.) or set a custom interval.

### Smart Contract Event

Triggers when a specific smart contract emits an event on-chain.

When to use: Reacting to swaps, transfers, mints, burns, liquidations, governance
votes, or any on-chain event.

Examples:
- Token contracts: trigger on transfers, approvals, burns
- DEX contracts: trigger on swaps, liquidity additions, pair creation
- NFT contracts: trigger on mints, transfers, sales

Config: Contract address, event name, chain ID.

What you can do with it:
- Send real-time alerts with transaction details (amounts, addresses, event types)
- Initiate follow-up actions (token transfers, trades, contract writes)
- Save event data to a database for analytics and reporting

### Wallet Event (Address Activity)

Triggers when a specific wallet address has on-chain activity.

When to use: Whale watching, portfolio alerts, wallet monitoring, detecting
incoming payments or airdrops.

Config: Wallet address, chain ID.

### Telegram Chatbot

Triggers when a user sends a message to a connected Telegram bot. The user creates
a Telegram bot, connects it to K3, and the workflow runs every time someone sends
the bot a message. The message content is passed into the workflow as input.

When to use: Building conversational AI agents on Telegram — users can chat with
a bot that has access to blockchain data, AI analysis, and any K3 workflow
functions. Think of it as giving users a personal on-chain assistant in their
Telegram chat.

Examples:
- User sends a wallet address → workflow reads the wallet, AI analyzes it, replies
  with a portfolio overview
- User asks "what's the price of ETH?" → AI Agent with CoinGecko MCP fetches the
  data and replies in the chat
- User sends a token name → workflow pulls market data, runs AI analysis, sends
  back a summary

Config: Telegram bot token, connected to K3 platform.

---

## Read Functions (Data Input)

These fetch data that downstream nodes can use.

### Custom Input

Accepts user-provided parameters at runtime. Useful for on-demand workflows where
the user specifies what to analyze each time (e.g., "which token?" or "which
wallet?").

Config: Define input fields with key, name, and default value.

### Read API

Makes an HTTP request to any REST or GraphQL API. This is the most flexible data
input — if a service has a public API, Read API can call it.

When to use: Calling CoinGecko, DeFiLlama, protocol-specific REST APIs, GraphQL
endpoints, or any other web API.

Config: URL, method (GET/POST), headers, body.

### Read Smart Contract

Queries smart contract data directly on any supported blockchain. Reads contract
state without needing an API intermediary.

When to use: Getting on-chain data directly — pool reserves, token balances,
contract parameters, governance state, or any public function on a smart contract.

Examples:
- Read a Uniswap pair contract to get current reserves
- Read an ERC20 token's totalSupply or balanceOf
- Read a lending protocol's interest rates directly from the contract

Config: Contract address, function to call, chain ID, function parameters.

### Read Market Data

Retrieves up-to-date token prices, volumes, and other market metrics. A built-in
convenience function for common market data needs.

When to use: Quick token price lookups, volume data, market cap, or other
standard market metrics without needing to configure a specific API.

### Read Wallet

Accesses wallet data including balances, token holdings, transfers, and transaction
history.

When to use: Portfolio tracking, wallet balance monitoring, transaction history
analysis.

Config: Wallet address(es), chain ID.

### Read NFT

Gets detailed NFT data: collections, floor prices, traits, volumes, account
holders, and more.

When to use: NFT portfolio tracking, collection monitoring, floor price alerts,
trait analysis, holder analytics.

### Read Graph

Fetches data from TheGraph protocol using custom GraphQL queries. Powerful for
complex on-chain analytics and DeFi metrics where a subgraph exists.

When to use: Querying DEX pool data (TVL, volume, fees, swap history), DeFi
protocol metrics, or any data indexed by a TheGraph subgraph.

Config: Subgraph endpoint URL, GraphQL query.

Note: You need to know the subgraph URL and schema. Search the web for
`{protocol name} subgraph` to find endpoints. Different chains have different
subgraph deployments.

### Read Deployment

Pulls output from your own custom-deployed code on K3. If a user has deployed
a custom function via K3's Innovate/Deploy feature, this reads its output.

When to use: Integrating custom code, proprietary data sources, or specialized
computations that aren't available through other read functions.

---

## AI Functions

### AI Service

Integrates AI models to summarize, analyze, or transform data. The basic AI
function — give it a prompt and data, get back analysis.

Supported models: Gemini (free via K3 credits), OpenAI, Claude (Anthropic).

When to use: Summarizing data, generating reports, formatting output, simple
analysis tasks.

### AI Web Scraper

Automatically extracts, structures, and summarizes content from web pages.

When to use: Getting data from websites that don't have APIs, monitoring web
pages for changes, extracting structured data from unstructured web content.

### AI Conditional (AI Routing)

Uses AI to analyze a situation and make a decision about workflow direction.
Enables branching logic based on AI judgment.

When to use: "Only alert me if the change is significant", "Route high-priority
events differently", or any conditional logic that's too complex for simple
if/else rules.

### AI Agent

Autonomous AI agent with advanced reasoning, tool use, and multi-step logic.
The most powerful AI function — it can decide what to do, call tools, and
orchestrate complex sequences.

When to use: Complex lookups where the AI needs to decide what to fetch,
multi-step analysis, or tasks requiring judgment and tool access.

Tool access options:
- **Web3 Data Fetcher (Uniblock)**: Lets the AI fetch on-chain data like
  historical prices, wallet transactions, etc.
- **MCP Server**: Connect to any MCP-compatible service (TheGraph, Google
  Sheets, email, databases, browsers, etc.)

### MCP Server Tool

Connects to any external service that supports Model Context Protocol. This
extends workflows beyond K3's built-in functions.

When to use: Integrating with Google Sheets, Gmail, Stripe, SQL databases,
browsers, cloud servers, or any other MCP-compatible service.

Config: MCP SSE endpoint URL, authentication credentials.

---

## Write Functions (Output & Actions)

### Write API

Sends data to any external or internal API via HTTP POST. The flexible output
function — if a service has an API, Write API can push data to it.

When to use: Sending data to webhooks, posting to external systems, triggering
actions in other platforms.

Config: URL, method, body, credentials.

### Write Smart Contract

Interacts with smart contracts to write or update on-chain data. Executes
transactions on the blockchain.

When to use: Automating on-chain actions like approvals, deposits, withdrawals,
or any smart contract interaction that changes state.

### S3 (Decentralized Storage)

Stores data to cloud storage (like AWS S3).

When to use: Archiving workflow outputs, storing historical data, saving reports
for later retrieval.

---

## DeFi & Trading Functions

These execute actual trades and token operations on-chain.

### Coinbase

Automates trading and asset operations on Coinbase.

When to use: Buying/selling tokens, portfolio rebalancing, or any Coinbase
trading automation.

### Uniswap

Executes trades and swaps on Uniswap automatically.

When to use: DEX trading automation, arbitrage, automated position management.

### Kyberswap

Automates DeFi swaps and liquidity management on Kyberswap.

When to use: Cross-DEX swap optimization, liquidity provision automation.

### Hyperliquid

Trades on Hyperliquid for DeFi automation.

When to use: Perps trading, leveraged position automation.

### Token Transfer

Moves tokens between wallets securely and automatically, triggered by any
workflow logic.

When to use: Automated payments, treasury management, token distribution,
conditional transfers based on alerts or analysis.

---

## Notification Functions

### Email

Sends custom email notifications with dynamic content from the workflow.

When to use: Daily reports, alert emails, formatted analysis deliveries.

Note: Requires an email integration (like Composio) to be connected on the team.

### Telegram

Sends real-time messages or alerts via Telegram.

When to use: Instant alerts, quick notifications, real-time monitoring updates.

Config: Bot token, chat ID.

### Slack

Sends data-driven updates to Slack channels or users.

When to use: Team notifications, shared monitoring alerts, workflow status updates.

---

## Utility Functions

### Notes

Adds comments or explanations directly in the workflow. Non-executable — purely
for documentation and clarity when viewing the workflow in the visual builder.

---

## Custom Deployments

Beyond the built-in functions, users can deploy their own code (Python, JavaScript,
etc.) as workflow steps via K3's Innovate feature. This enables:
- Unique business logic
- Connections to private APIs
- Proprietary data sources or models
- Custom computations

Deployed code becomes available as a workflow node via **Read Deployment**.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)