Lesson 4: Your First Forta Agent (Installing the SDK and Writing Your First Bot)

This is the first hands-on meditation of your training.

Until now, you have been contemplating the blockchain: its heartbeat, its transactions, its smart contracts. Today, you begin shaping it.

---

What Is the Forta Agent SDK?

The Forta Agent SDK is a set of developer tools that allows you to build bots (also called agents) that monitor blockchain data and emit alerts when suspicious behavior is detected.

Each agent is simply a small JavaScript or TypeScript project with two main components:

• A handleTransaction or handleBlock function that processes chain data

• Logic to decide whether that data is “suspicious” or worth alerting

It runs in an isolated environment, triggered by Forta scan nodes, using your detection logic.

In summary:
You write the logic. Forta runs it. Everyone benefits.

---

What You Need Installed Before Starting

To build and run Forta bots, you need:

• Node.js (v16 or higher)

• NPM (comes with Node)

• Forta CLI

• Basic understanding of JavaScript

Optional (but helpful):

• VS Code or any code editor

• GitHub account (for sharing your bots later)

• Etherscan or Tenderly for testing real txs

---

Install the Forta CLI

Let’s set up your system for bot development.

Step 1: Install Node.js

Install from the official site:

https://nodejs.org/

You can verify it’s working:

node -v 
npm -v

Step 2: Install the Forta CLI

The CLI helps you set up and run agents locally.

npm install -g forta-agent

Then test the installation:

forta --version

Step 3: Create Your First Agent

Navigate to a new folder in your terminal:

mkdir detect-high-eth-transfer 
cd detect-high-eth-transfer forta-agent init

Choose “TypeScript” or “JavaScript” when asked.

It creates the following structure:

detect-high-eth-transfer/
├── src/ 
│ └── agent.js 
├── test/ 
│ 
└── agent.spec.js
 ├── package.json
 └── forta.config.json

You now have a working bot structured and ready to modify.

---

Writing a Simple Detection Bot

Open src/agent.js and modify the logic inside handleTransaction().

Here’s a basic example that triggers an alert if any transaction transfers more than 1,000 ETH:

const { Finding, FindingSeverity, FindingType } = require("forta-agent"); 

function handleTransaction(txEvent) {
const findings = []; 

const largeTransfers = txEvent.traces.filter(trace => 
trace.action.value && parseInt(trace.action.value) > 1000 * 1e18 
); 

if (largeTransfers.length > 0) { 
findings.push(Finding.fromObject({
   name: "High ETH Transfer", 
   description: "Transaction contains a high ETH transfer",
   alertId: "HIGH-ETH-TRANSFER", 
   severity: FindingSeverity.Medium, 
   type: FindingType.Suspicious, 
   metadata: { 
      count: largeTransfers.length.toString()
 } 
 })); 
} 

return findings; 
} 

module.exports = {
  handleTransaction, 
};

---

How to Run Your Bot Locally

To simulate a transaction and test your bot:

npm install 
npm run test

This will execute the logic in test/agent.spec.js.

You can customize that test to simulate specific tx traces or mock events from real transactions.

---

Example Project Folder

You can download the full working Forta bot folder for this lesson here:

detect-high-eth-transfer-agent

That includes:

• The working agent logic

• Basic tests

• All dependencies ready to run

---

Why This Lesson is important

Everything in this training is based on this lesson.

Without knowing how to:

• Set up bots

• Write handleTransaction() logic

• Simulate attacks locally

...you cannot begin to monitor or protect.

From this point forward, you are no longer just observing the chain. You are participating in its defense.

In the next lesson, we will improve this bot by decoding events from real ERC-20 transfers, and use that knowledge to detect unusual behavior in live token activity.

Until next meditation,
The Blockchain Security Monk