Forem: IQ AI

How to Build Your First AI Agent in TypeScript with ADK-TS

Timonwa Akintokun — Wed, 19 Nov 2025 08:00:00 +0000

As TypeScript developers, we're always looking for ways to make our applications smarter and more interactive. While integrating AI into our apps has traditionally meant writing complex Python code or managing large language models, that's changing. Thanks to frameworks like ADK-TS, we can now build intelligent AI agents right in our TypeScript projects.

In this tutorial, we'll build a simple multi-agent system that can handle weather queries and tell jokes. You'll learn how to create AI agents that can:

Understand and respond to natural language requests
Use external APIs and tools to fetch real data
Work together as a coordinated system
Handle different types of user queries intelligently

By the end of this tutorial, you'll have a working AI agent system and understand how to extend it for your own projects. Let's get started.

What are AI Agents?

When we talk about AI agents, we're talking about making our applications smarter in how they handle user requests. Instead of just responding to specific commands, an AI agent can understand what a user wants and figure out how to help them.

Think about a weather application. A traditional app might require users to click specific buttons or type exact city names. An AI agent, on the other hand, can understand natural questions like "Do I need an umbrella today?" or "What's the weather like in London?" and know how to get that information.

What makes AI agents different from regular AI integrations? It's their ability to:

Understand the context of conversations
Use different tools and APIs when needed
Make decisions about how to handle requests
Work together with other agents to solve problems

Why Build AI Agents in TypeScript?

As TypeScript developers, we're used to building well-structured, type-safe applications. While Python has been the go-to language for AI development, TypeScript offers some real advantages:

We can use our existing TypeScript skills and tools
We get great IDE support and type checking
Our agents can easily integrate with our TypeScript/JavaScript backends
We can seamlessly add AI agents to existing web applications
We can deploy our agents alongside our existing services

Plus, with frameworks like ADK-TS, we don't need to learn complex AI concepts or deal with model training. The framework handles the heavy lifting for you—model integrations, built-in session and memory management, tool handling, observability, and more. We can just focus on building useful features using familiar TypeScript patterns.

What Makes ADK-TS Different

ADK-TS is a TypeScript-first framework that simplifies building AI agents and multi-agent systems. It provides type-safe APIs using TypeScript and Zod, supports multiple LLM providers (OpenAI, Anthropic, Gemini, and more), enables streaming responses for real-time interactions, and includes built-in memory management for stateful conversations.

You can also orchestrate multiple agents to work together, create reusable tools for external integrations, and deploy agents as HTTP servers or integrate them into existing applications. The framework uses familiar patterns, such as fluent builders and factory functions, that fit naturally into your TypeScript workflow.

Building Our First AI Agent System

We'll build a multi-agent system that has one root agent and coordinates two specialized sub-agents:

Root agent (router): accepts user requests and delegates work to the appropriate sub-agent
Weather agent: fetches current weather using a weatherTool
Joke agent: returns random jokes using a jokeTool

Each sub-agent has its own tools and logic, while the root agent focuses on routing requests. This structure gives us separation of concerns (changes to weather logic won't affect jokes), easier testing (test tools and agents can run in isolation), and the ability to add new agents without disrupting existing ones.

Let's set up our project.

Project Folder Structure

Here's a recommended structure for organizing your project:

my-first-ai-agent/
├── src/
│   ├── agents/
│   │   ├── weather-agent/
│   │   │   ├── tools.ts
│   │   │   └── agent.ts
│   │   ├── joke-agent/
│   │   │   ├── tools.ts
│   │   │   └── agent.ts
│   │   └── agent.ts          # Root agent
│   ├── env.ts
│   └── index.ts
├── .env
├── tsconfig.json
└── package.json

This structure helps keep your code organized by separating each agent into its own folder with its tools. You can adapt this layout to fit your preferences, but this approach makes it easier to maintain and scale as you add more agents.

Setting Up the Project

Next, open your terminal and run the following commands:

mkdir my-first-ai-agent
cd my-first-ai-agent
pnpm init

Install the necessary dependencies:

pnpm add @iqai/adk dotenv zod
pnpm add -D typescript @types/node tsx

Create a basic TypeScript configuration in tsconfig.json:

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  }
}

Create a .env file to store your environment variables:

# .env
GOOGLE_API_KEY=your_google_api_key_here
LLM_MODEL=gemini-2.5-flash # Default model

You can get a Google API key from the Google AI Studio.

ADK-TS supports multiple LLM providers, but we will be using Gemini, which is the default provider. To learn more about configuring different LLM providers, check out the ADK-TS documentation.

Lastly, create a .env.ts file to load the environment variables:

// src/env.ts
import { config } from "dotenv";
import { z } from "zod";

config();

export const envSchema = z.object({
 GOOGLE_API_KEY: z.string(),
 LLM_MODEL: z.string().default("gemini-2.5-flash"),
});

export const env = envSchema.parse(process.env);

This sets up our project structure and configuration. Next, we'll start building our tools and agents.

Agent Interaction Flow

Before we dive into the code, let's visualize how our multi-agent system works:

The diagram shows the complete flow of a user request through our system:

User makes a request - The user asks a natural-language question, such as "What's the weather in London?"
Root agent analyzes - The root agent receives the request and determines which specialized agent should handle it
Root agent delegates - Based on the analysis, the root agent routes the task to the appropriate sub-agent (Weather Agent in this example)
Selected sub-agent executes - Only the chosen sub-agent activates and uses its tools to fetch data from external APIs
Response delivered - The sub-agent returns data through the root agent back to the user

If the user had asked for a joke instead, the Joke Agent would be selected, while the Weather Agent would remain inactive. This selective activation ensures efficiency and clarity in handling requests.

Now, let’s start building our tools and agents.

Creating Tools for Our Agents

Before we build the agents, we need to create the tools they will use. Tools are reusable components that encapsulate specific functionality, making it easier for agents to perform tasks. They extend the agent's capabilities by enabling it to interact with external APIs or services in a structured way.

We will create two tools: one for fetching weather information and another for fetching jokes. These tools will wrap external APIs and provide a clean interface for our agents to use.

Create a new file src/agents/weather-agent/tools.ts:

// src/agents/weather-agent/tools.ts
import { createTool } from "@iqai/adk";
import * as z from "zod";

export const weatherTool = createTool({
  name: "get_weather",
  description: "Get current weather for a city",
  schema: z.object({
    city: z.string().describe("City name"),
  }),
  fn: async ({ city }) => {
    try {
      const response = await fetch(
        `https://wttr.in/${encodeURIComponent(city)}?format=3`
      );
      return await response.text();
    } catch {
      return `Weather unavailable for ${city}`;
    }
  },
});

Next, create src/agents/joke-agent/tools.ts:

// src/agents/joke-agent/tools.ts
import { createTool } from "@iqai/adk";

export const jokeTool = createTool({
 name: "get_joke",
 description: "Fetches a random joke",
 fn: async () => {
  try {
   const response = await fetch(
    "<https://official-joke-api.appspot.com/random_joke>",
   );
   return await response.text();
  } catch {
   return "Joke unavailable right now.";
  }
 },
});

These tools provide the basic capabilities our agents will need. The weather tool can fetch weather information for any city, while the joke tool retrieves random jokes from an API.

Creating Our Specialized Agents

Now that we have our tools ready, let's create the agents that will use them. Each agent will focus on one specific task - either providing weather information or telling jokes.

In src/agents/weather-agent/agent.ts, create the weather agent:

// src/agents/weather-agent/agent.ts
import { LlmAgent } from "@iqai/adk";
import { env } from "../../env";
import { weatherTool } from "./tools";

export const getWeatherAgent = () => {
  const weatherAgent = new LlmAgent({
    name: "weather_agent",
    description: "provides weather for a given city",
    model: env.LLM_MODEL,
    tools: [weatherTool],
  });

  return weatherAgent;
};

Similarly, in src/agents/joke-agent/agent.ts, create the joke agent:

// src/agents/joke-agent/agent.ts
import { LlmAgent } from "@iqai/adk";
import { env } from "../../env";
import { jokeTool } from "./tools";

export const getJokeAgent = () => {
  const jokeAgent = new LlmAgent({
    name: "joke_agent",
    description: "provides a random joke",
    model: env.LLM_MODEL,
    tools: [jokeTool],
  });

  return jokeAgent;
};

Each agent is configured with a specific purpose and the tools it needs to do its job. The weather agent knows about weather-related queries, while the joke agent handles requests for humor.

Creating the Root Agent

The root agent acts as a coordinator, directing user requests to the appropriate specialized agent. When a user asks a question like "What's the weather in Paris?" or "Tell me a joke," the root agent determines which sub-agent should handle the request. If the user asks a question that doesn't fit either category, the root agent can respond with a default message or handle it gracefully.

Here's how we set it up in src/agents/agent.ts:

// src/agents/agent.ts
import { AgentBuilder } from "@iqai/adk";
import { env } from "../env";
import { getJokeAgent } from "./joke-agent/agent";
import { getWeatherAgent } from "./weather-agent/agent";

export const getRootAgent = () => {
  const jokeAgent = getJokeAgent();
  const weatherAgent = getWeatherAgent();

  return AgentBuilder.create("root_agent")
    .withDescription(
      "Root agent that delegates tasks to sub-agents for telling jokes and providing weather information."
    )
    .withInstruction(
      `
     You are a routing agent. Analyze the user's request and delegate to the appropriate sub-agent:

    - For ANY request about weather, weather conditions, temperature, or location-based weather queries: delegate to weather_agent
    - For ANY request about jokes, humor, comedy, or asking to tell a joke: delegate to joke_agent

    Do not answer questions yourself. Always delegate to the appropriate sub-agent based on the request type.`
    )
    .withModel(env.LLM_MODEL)
    .withSubAgents([jokeAgent, weatherAgent])
    .build();
};

Putting It All Together

Finally, let's create our main application file that uses our agent system. In src/index.ts:

// src/index.ts
import * as dotenv from "dotenv";
import { getRootAgent } from "./agents/agent";

dotenv.config();

async function main() {
  const questions = ["how is weather in london?", "tell me a random joke"];

  const { runner } = await getRootAgent();

  for (const question of questions) {
    console.log(`📝 Question: ${question}`);
    const response = await runner.ask(question);
    console.log(`🤖 Response: ${response}`);
  }
}

main().catch(console.error);

This code creates our agent system and tests it with a couple of simple questions. The root agent automatically figures out which specialized agent should handle each request.

Running Your Agent

To run your agent system, add these scripts to your package.json:

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

And run your agent using:

pnpm dev

You should see output like:

📝 Question: how is weather in london?
🤖 Response: The weather in London is ⛅️ +14°C.
📝 Question: tell me a random joke
🤖 Response: Why do programmers prefer dark mode? Because light attracts bugs!

Using the CLI for Interactive Testing

Instead of writing test scripts, you can interact with your agent directly using the ADK-TS CLI. First, install the CLI:

# Install globally
pnpm add -g @iqai/adk-cli

# Or use npx without global installation
npx @iqai/adk-cli

The CLI provides two ways to test your agents:

Terminal-Based Chat (adk run): Start an interactive chat session in your terminal for quick testing and experimentation.

Web-Based Interface (adk web): Launch a local web server with a visual chat interface for a more user-friendly experience.

Both methods auto-discover your agents from the src/agents directory and let you test without writing any scripts. For detailed installation and usage instructions, check out the CLI documentation.

Using ADK-TS Built-in Tools

ADK-TS also includes several built-in tools you can use right away without creating custom implementations. For example, if you want to add web search capabilities to your agent, you can use the built-in GoogleSearch tool:

import { GoogleSearch, LlmAgent } from "@iqai/adk";
import { env } from "../env";

export const getSearchAgent = () => {
  return new LlmAgent({
    name: "search_agent",
    description: "searches the web for information",
    model: env.LLM_MODEL,
    tools: [new GoogleSearch()], // Use the built-in tool
  });
};

Check out the tools documentation to see what's available and how to use them.

Taking Your Agent Further

While our weather and joke example is straightforward, you can apply these same patterns to build more sophisticated agents. Here are some real-world applications:

Customer Service Agent

You could extend this pattern to create a customer service agent that answers product questions using a product database, handles order status inquiries by connecting to your order system, escalates complex issues to human support when needed, and maintains conversation context across multiple questions.

Development Assistant

Create an agent that helps with coding tasks by analyzing pull requests and suggesting improvements, helping debug code by running tests and analyzing logs, generating documentation from code comments, and reviewing code for security issues.

Blockchain Portfolio Agent

Build an agent that helps users manage their cryptocurrency investments by tracking portfolio performance across multiple exchanges, analyzing market trends using price data APIs, sending alerts for significant price changes, and providing insights on potential investment opportunities based on historical data and current market conditions.

Conclusion

In this tutorial, we've built a multi-agent system using TypeScript and ADK-TS. We've seen how to create specialized agents that handle specific tasks, equip our agents with tools to give them real capabilities, coordinate multiple agents through a root agent, and structure our code in a maintainable way.

This is just the beginning of what you can do with AI agents in TypeScript. Whether you're building a customer service system, a blockchain portfolio manager, or something entirely new, the patterns we've covered here will help you create organized and effective agent-based applications.

Next Steps

To view the complete code used in this tutorial, you can:

Run npx @iqai/adk-cli new --template simple-agent my-first-agent to scaffold a new project
Visit the GitHub repository to explore the source code

Ready to build your own AI agent? Check out the ADK-TS documentation for more examples and advanced features.

Autonomous AI Agents on Blockchain with ADK-TS & NEAR

Timonwa Akintokun — Mon, 13 Oct 2025 08:00:00 +0000

Most blockchain applications today require constant human intervention. Smart contracts sit idle until someone triggers them. DeFi protocols need manual rebalancing. Oracle feeds depend on centralised operators pushing data.

But what if your blockchain applications could think and act on their own?

The ADK-TS × NEAR Shade Agent template makes this vision a reality. It combines the intelligence of modern AI with the autonomy that blockchain technology promises, creating agents that can monitor markets, analyse data, make decisions, and execute transactions without any human involvement.

What Makes This Template Different

Unlike typical blockchain integrations that bolt AI onto existing infrastructure, this template was designed from the ground up for true autonomy. The agents you build don't just respond to requests—they actively monitor conditions, reason about complex scenarios, and take action when needed.

The template demonstrates this through a practical example: an AI agent that monitors Ethereum market sentiment by analyzing Reddit headlines, fetches real-time price data from CoinGecko, and autonomously signs transactions to update an on-chain oracle contract with no humans required.

How ADK-TS Works with NEAR Shade Agents

The magic happens when we combine two technologies that were practically made for each other: ADK-TS provides the intelligence, whilst NEAR Shade Agents handle the blockchain execution.

ADK-TS Framework: Building Intelligent AI Agents

ADK-TS (Agent Development Kit for TypeScript) brings genuine AI capabilities to blockchain development. Rather than simple chatbots or API wrappers, ADK-TS lets you build agents that can reason about complex scenarios, coordinate with other agents, and maintain memory across interactions.

const { runner } = await AgentBuilder
  .create("crypto-oracle-agent")
  .withModel("gemini-2.5-flash")
  .withDescription("Autonomous crypto market analyst")
  .withInstruction("Monitor ETH price and sentiment, update oracle")
  .asParallel([priceAgent, sentimentAgent])
  .build();

What makes ADK-TS special is its multi-agent orchestration. Instead of building one massive AI system that tries to do everything, you create specialised agents that excel in specific areas. One agent might focus on market analysis, whilst another handles transaction logic—they work together seamlessly.

NEAR Shade Agent: Secure Blockchain Transaction Execution

Here's where things get interesting. NEAR Shade Agents solve the biggest challenge in AI-blockchain integration: how can an AI system sign transactions without compromising security?

The answer lies in Account Abstraction and Trusted Execution Environments (TEEs). Each agent gets its own NEAR account, complete with private keys stored securely in trusted hardware called Trusted Execution Environments (TEEs). Through NEAR's Chain Signatures technology, these agents can sign transactions not just on NEAR, but on any blockchain—Ethereum, Bitcoin, you name it.

This means AI agents can finally operate independently across multiple blockchains, making decisions and executing transactions without any human intervention.

Trusted Execution Environment(TEE) Security for Production AI Agents

The entire architecture is designed with production-grade security from the ground up. The Trusted Execution Environments provide hardware-level protection for agent private keys, meaning they're safe even from the hosting infrastructure itself. This goes beyond software security to hardware-guaranteed protection with cryptographic proof.

The decentralised architecture means there are no single points of failure. Agents run across distributed TEE networks, making the entire system censorship-resistant and highly available. Everything is open source and auditable, allowing you to verify exactly how your agent operates while keeping its operations secure.

Building an Ethereum Price Oracle AI Agent

The template includes a fully functional Oracle agent that demonstrates the complete autonomous pipeline:

1. Creating Multi-Agent Systems

The system uses multiple specialised agents working in parallel:

// Price Agent (src/agents/eth-price-agent/)
export const getEthPriceAgent = () => {
  return new LlmAgent({
    name: "eth_price_agent",
    description: "Provides the current Ethereum (ETH) price",
    instruction: "When asked about ethereum, provide its price.",
    model: env.LLM_MODEL,
    tools: [ethPriceTool],
  });
};

// Sentiment Agent (src/agents/eth-sentiment-agent/)
export const getEthSentimentAgent = () => {
  return new LlmAgent({
    name: "eth_sentiment_agent",
    description: "Provides Ethereum sentiment based on latest headlines",
    instruction:
      "Analyse headlines and respond with 'positive', 'negative', or 'neutral'",
    model: env.LLM_MODEL,
    tools: [ethHeadlinesTool],
    outputKey: "sentiment",
  });
};

2. AI Tools for Real-Time Data Collection and Analysis

The agents use sophisticated tools to gather real-world data:

// Price tool fetches from CoinGecko API
export const ethPriceTool = createTool({
  name: "get_eth_price",
  description: "Fetches the current Ethereum (ETH) price in USD",
  fn: async (_, context) => {
    const response = await fetch(
      "https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd"
    );
    const data = await response.json();
    context.state.set("price", data.ethereum.usd);
    return `Current Ethereum price: $${data.ethereum.usd} USD`;
  },
});

// Sentiment tool analyses Reddit headlines
export const ethHeadlinesTool = createTool({
  name: "get_eth_headlines",
  description: "Get latest Ethereum-related news headlines from Reddit",
  fn: async (_, context) => {
    const parser = new Parser();
    const feed = await parser.parseURL(
      "https://www.reddit.com/r/ethereum/.rss"
    );
    const headlines = feed.items.map(item => item.title).slice(0, 10);
    context.state.set("headlines", headlines.join("\\\\n"));
    return headlines;
  },
});

3. Autonomous Transaction Signing and Blockchain Execution

The magic happens when the agent autonomously signs and broadcasts transactions:

// Agent gathers data
const { sessionService, runner, session } = await getRootAgent();
const response = await runner.ask("Give ethereum's price and sentiment");

// Extract intelligence from agent state
const { price, sentiment } = currentSession.state;

// Prepare blockchain transaction
const { transaction, hashesToSign } = await getMarketDataPayload(
  price,
  sentiment,
  contractId
);

// Agent autonomously signs transaction
const signRes = await requestSignature({
  path: "ethereum-1",
  payload: uint8ArrayToHex(hashesToSign[0]),
});

// Broadcast to blockchain
const txHash = await Evm.broadcastTx(signedTransaction);

Blockchain AI Agents vs Traditional Web3 Applications

Current Web3 applications have significant limitations that prevent mainstream adoption and truly decentralised operations.

Current Web3 Limitations

Most blockchain applications today require constant babysitting. Smart contracts are reactive rather than proactive—they wait for external triggers instead of monitoring conditions and acting independently.

DeFi protocols require manual rebalancing due to changing market conditions. Oracle feeds depend on centralised operators to push data updates. Users must understand complex wallet interfaces, gas fees, and transaction signing just to interact with basic features.

ADK-TS × NEAR Shade Agent Solution

This template changes the game by enabling truly autonomous blockchain operations. AI agents can continuously monitor market conditions, analyze complex data from multiple sources, make intelligent decisions based on changing circumstances, and execute transactions across various blockchains without human involvement. The user experience transforms from technical complexity to natural language interactions.

Building Your First Autonomous Agent

Getting started is surprisingly straightforward. You can have a fully functional autonomous agent running in minutes, not hours.

# Create new project with the NEAR Shade Agent template
npx @iqai/adk-cli new --template shade-agent my-shade-agent
cd my-autonomous-agent
pnpm install

The template comes with everything configured, but you'll want to add your own credentials.

Copy the example environment file and fill in your details:

cp .env.development.local.example .env.development.local

You'll need your NEAR account details, a Google API key for the Gemini LLM, and a Phala Cloud API key. The template documentation explains where to get each of these.

For production deployment, it's a single command:

pnpm dlx @neardefi/shade-agent-cli

This builds your project, creates a Docker image, deploys it to Phala Cloud's TEE network, and gives you a live URL to interact with your agent's endpoints. Your agent is now running autonomously in a secure, decentralised environment.

REST API Endpoints for AI Agent Management

Once your agent is running, you can interact with it through clean REST APIs. The template provides three key endpoints that give you complete visibility into your agent's operations:

GET /api/agent-account: The agent account endpoint shows you the NEAR account that your agent is using, along with its current balance. This is useful for monitoring whether your agent has sufficient funds for its operations.
GET /api/eth-account: The Ethereum account endpoint displays the derived Ethereum address that your agent uses for cross-chain transactions, plus its balance. This demonstrates the power of NEAR's chain signatures—your agent can operate on multiple blockchains using a single NEAR account.
POST /api/transaction: The transaction endpoint is where the magic happens. When you call this endpoint, your agent springs into action: it gathers market data, analyses sentiment, and autonomously signs and broadcasts a transaction to update the oracle contract.

You can test these endpoints directly:

curl <https://your-agent.phala.network/api/transaction>

This isn't just a demonstration—it's a fully functional autonomous system that could handle real-world oracle operations.

AI Agent Use Cases Beyond Price Oracles

This template is just the beginning. The ADK-TS × NEAR Shade Agent architecture enables:

DeFi AI Applications

Automated yield farming with AI risk assessment
Dynamic liquidity provision based on market conditions
Intelligent trading bots with cross-chain capabilities

Gaming & NFT AI Integrations

Autonomous NPCs with persistent blockchain identities
Dynamic NFT metadata updated by AI analysis
Cross-chain gaming assets managed by agents

Blockchain Infrastructure Automation

Decentralised monitoring and alerting systems
Autonomous governance participation and voting
Cross-chain bridge management and optimisation

Enterprise Blockchain AI Solutions

Supply chain automation with AI verification
Regulatory compliance monitoring and reporting
Business process automation on blockchain

The Future of Autonomous Blockchain AI Agents

The ADK-TS × NEAR Shade Agent template represents the first step towards a truly autonomous Web3 ecosystem. As AI continues to advance and blockchain infrastructure matures, we envision:

Autonomous DAOs governed entirely by AI agents
Self-optimising protocols that adapt to market conditions
Cross-chain AI networks collaborating on global problems
Natural language Web3 interfaces for mainstream adoption

Start Building AI Blockchain Agents Today

The autonomous Web3 future is here, and it's easier to build than ever before.

To try the template, run the following command:

npx @iqai/adk-cli new --template shade-agent my-shade-agent

Resources

ADK-TS x402: AI Agents with On-Chain Crypto Payments

Timonwa Akintokun — Mon, 06 Oct 2025 08:00:00 +0000

AI agents are becoming smarter, faster, and more useful — but one thing they still struggle with is payments. How does an agent pay for an API call? How does a developer charge for agent services without setting up clunky billing systems?

This is the gap the x402 payments protocol (from Coinbase) is designed to solve. And with our ADK-TS (Agent Development Kit for TypeScript) starter template, we show how developers can build AI agents with native crypto payments — turning pay-per-use into reality.

What is the x402 payments protocol?

The x402 protocol is an open standard from Coinbase that makes HTTP 402 Payment Required usable for the modern web.

The flow is elegantly simple: when you request a paid resource, the server replies with a 402 Payment Required response that tells you exactly how much to pay, what token to use (e.g., USDC), and where to send it. Your client then makes the payment on-chain and retries the request with proof of payment in the X-PAYMENT header. Finally, the server verifies the payment and unlocks the content or API.

This creates a universal pay-to-access system for the internet, powered by crypto micropayments. Unlike credit cards, it works for fractions of a cent, settles instantly, and is globally accessible.

How x402 micropayments work for digital content: Request Paid Resource → 402 Payment Required → Make Payment → Request Payment Resource Again → Instant unlock.

What is ADK-TS? (Agent Development Kit for TypeScript)

ADK-TS is a TypeScript framework for building AI agents, designed to give developers a robust, type-safe foundation for everything from simple chatbots to complex multi-agent systems.

The framework provides built-in support for multiple AI models (OpenAI, Claude, Gemini, etc.), along with essential tools for memory, streaming, and session management.

What sets it apart is its seamless integration capabilities with external services and APIs. With ADK-TS, you don't just write agents — you build enterprise-grade AI systems without boilerplate.

⭐️ Star on GitHub

Who is IQ AI?

At IQ AI, we're building the Agent Tokenization Platform — a marketplace where AI agents can be tokenized, traded, and monetized. Developers can publish agents, expose premium features, and even enable agents to transact with one another.

To make this work, agents need the ability to charge and pay seamlessly. That's why we've integrated x402 protocol payments into ADK-TS, creating the foundation for autonomous, monetized AI agents.

How ADK-TS and x402 work together

When you combine ADK-TS agents with the x402 protocol, you unlock a new capability: agents that can charge and pay on-chain automatically. Our starter template demonstrates this through three key components working in harmony:

The server acts as an x402 paywall proxy, defining free and paid API routes whilst enforcing pricing and verifying payments.
The agent, built with ADK-TS, intelligently uses free tools for basic operations and paid tools for premium features.
The client employs axios middleware with wallet integration to handle x402 payment challenges, make on-chain payments in USDC on Base testnet, and retry requests with proof.

The user experience feels seamless:

The agent greets you and provides free information, such as current API prices.
When you request a paid action, it clearly states the price and asks for approval.
Once approved, the payment processes automatically, and the result is returned.
No API keys. No subscriptions. Just pay-per-call with crypto.

Understanding the Setup

One of the most elegant aspects of this template is that pricing and payment logic live on the server, not buried inside your agent code. This architectural decision brings significant advantages:

You can change your pricing without redeploying agents
The agent stays clean and focused only on using tools rather than enforcing payments
Users get a transparent experience where the agent can tell them upfront how much an action costs before they approve it.

This separation of concerns makes scaling effortless. If the upstream API changes or you decide to tweak the costs of certain actions, your agent doesn't break — the proxy server handles it gracefully.

Deep dive: Agent Template Architecture

Codebase architecture of the ADK-TS x402 template: a server layer enforces x402 pricing and payments, while the agent layer uses free and paid tools to interact with users.

The IQ-x402 agent template is structured into two complementary parts that work together seamlessly:

The server component acts as an x402-paywalled proxy, forwarding requests to the IQ AI API whilst enforcing pricing and exposing a free /api/get-prices route so the agent can always display costs before asking for payment.
The agent component is a TypeScript agent built with ADK-TS tools, featuring both free and paid functionality. The GET_PRICES tool remains always available, providing transparency about costs.
The paid tools — GET_AGENT_INFO, GET_AGENT_STATS, GET_HOLDINGS, and GET_TOP_AGENTS — require on-chain payment before returning results, creating a natural division between free exploration and premium insights.

Looking at the implementation, you'll find the core logic distributed across three key files:

The server/src/index.ts defines the pricing map (PAID_ROUTES) and payment middleware, creating the economic backbone of the system.
The agent/src/agents/IQ-x402/tools.ts implements both the free and paid tools using the x402-enabled axios client.
Finally, agent/src/agents/IQ-x402/agent.ts contains the main agent logic that greets users, fetches prices proactively, and crucially asks for explicit consent before making any paid calls.

Testing the Template

Once everything is set up, running the template gives you a web UI powered by adk-web, where you can interact with the agent directly in your browser. The experience showcases the power of the x402 integration beautifully.

Free actions like fetching prices work instantly, giving users immediate value and transparency. When you request paid actions such as fetching token statistics, the x402 payment flow springs into action:

The agent requests the resource, and the server returns a 402 Payment Required response.
Your wallet prompts you to approve a small payment in Base Sepolia testnet USDC.
Once approved, the agent automatically retries the call and delivers the data.

Demo of the ADK-TS x402 agent template: the agent greets the user, displays free price info, and requests payment approval before executing paid actions.

💡 Tip: Grab some testnet USDC and ETH from the Base Sepolia faucets before testing, so you can experience the flow without spending real funds.

The Magic of the Combination - ADK-TS + x402

The real magic here lies in how ADK-TS and x402 complement each other perfectly. ADK-TS handles the intelligence side — memory, workflows, streaming, and multi-agent orchestration. Meanwhile, x402 handles the economics side — letting your agent earn, spend, and unlock access with on-chain micropayments.

Together, you can envision agents that sell access to their own tools or knowledge, pay each other for services in true machine-to-machine economies, and monetise data, statistics, or insights on demand without relying on subscriptions or advertisements.

This template serves as a starting point, but it demonstrates how powerful the model becomes: agents that are both intelligent and economically independent.

How users pay with x402 (wallet flow explained)

The payment experience extends beyond just servers receiving funds — users need an intuitive way to make payments with their wallet.

The flow works seamlessly in practice: when a user requests a paid action, the server replies with 402 Payment Required. The wallet integration kicks in, whether it's a browser wallet like MetaMask or Coinbase Wallet, an in-app wallet, or a facilitator service.

For human users, a wallet popup appears asking for approval ("Pay $0.05 USDC?"). For automated agents, the middleware can auto-pay microtransactions or forward the consent request appropriately.

Once payment is sent, the retry request includes an X-PAYMENT header with cryptographic proof. The server then verifies the payment and responds by unlocking the requested content, API data, or agent functionality.

This makes crypto micropayments feel as seamless as paying for coffee — but for digital services.

Why this matters for developers and the AI community

This starter template represents more than just a proof of concept — it's a glimpse into transformative possibilities.

Consider the shift from traditional subscription models to pay-per-API calls, where APIs can charge mere cents per request.

Imagine agent marketplaces where AI agents pay each other for data, models, or services.

Picture decentralised agent economies where agents earn, spend, and transact on-chain autonomously.

By combining ADK-TS and x402, we're enabling a future where AI agents are not just intelligent, but also economically autonomous.

Get started with the ADK-TS x402 template

The template runs on Base Sepolia testnet, allowing you to experiment risk-free using test USDC and ETH from faucets.

You'll receive a complete setup: an x402-enabled server with free and paid routes, an ADK-TS agent wired with both free and paid tools, and a wallet-enabled axios client that handles payments automatically.

Clone it, run pnpm run dev, and start experimenting with monetized AI agents today.

Final thoughts: AI + crypto payments = the future

The internet has waited decades for a standard way to implement pay-to-access functionality. With Coinbase's x402 payments protocol, that standard is finally here. With ADK-TS, we can seamlessly bring it into AI agents. And with IQ AI, we're building the ecosystem where these monetised agents can thrive.

This is just the beginning — the future of autonomous, pay-per-use AI is in your hands.

Resources

IQ AI x402 Agent Template - Our starter project combining ADK-TS with the x402 protocol
IQ AI Agent Tokenization Platform - Platform for creating, tokenising, and trading AI agents
ADK-TS GitHub Repository - The Agent Development Kit (ADK-TS) for TypeScript for building AI agents
ADK-TS Documentation - Comprehensive guides, API references, and examples
x402 Official Website - The official site for the x402 protocol, including examples and updates
x402 GitHub Repository (Coinbase) - The open-source implementation maintained by Coinbase

The ADK-TS Hackathon 2025 Is Live!

Timonwa Akintokun — Sat, 27 Sep 2025 08:00:00 +0000

Hey builders 👋

We’ve just launched the ADK-TS Hackathon 2025 on DoraHacks, and we couldn’t be more excited to see what you’ll create. For the next 4 weeks, developers from all over the world will be experimenting with ADK-TS (our TypeScript Agent Development Kit), pushing the limits of AI agents, and showing off what’s possible when great ideas meet the right tools. Full details, rules, and submissions can all be found on the DoraHacks event page.

Whether you’re hacking solo or teaming up with friends, this is your chance to:

Build something real with ADK-TS
Compete for a share of $4,000 in stablecoin prizes
Contribute to the growing ecosystem around AI agents

Tracks & Prizes

We’ve set up 3 main tracks and 5 bonus awards, so there’s room for different kinds of projects:

Main Tracks – $1,000 each

MCP Expansion – Build new Model Context Protocol (MCP) servers that expand what agents can connect to and do.
ADK-TS Agents – Create full-featured AI agents powered by ADK-TS.
Web3 Use Case – Explore blockchain + agent integrations that bring AI into Web3.

Bonus Awards – $200 each

Most Practical Real-World Use Case – The most “ready to use today” solution with obvious real-world value.
Best Bot Integration – Smart, useful, or fun agents running on Discord, Telegram, Slack, or other chat platforms.
Best Collaboration/Team Agent or MCP – Agents (or MCPs) that work together or boost teamwork/productivity.
Best Technical Implementation – Projects that push technical limits with clean, efficient, or innovative builds.
Best Contribution to ADK-TS – Meaningful extensions, templates, or utilities that make ADK-TS stronger for future devs.

👉 For track requirements, prize distribution, and eligibility, check the DoraHacks hackathon page.

Key Dates

Kickoff + Registration: Sept 25, 2025
Submission Deadline: Oct 23, 2025
Winners Announced: Oct 30, 2025

That gives you 4 weeks to build and 1 week for us to review everything and crown the winners.

What to Submit

To qualify, your project needs to:

Be built with ADK-TS
Live in a public GitHub repo
Include a demo video (max 5 minutes) showing how it works
Show how ADK-TS was used in the build
Include a live demo URL (if possible)

Extra resources and examples can be found in the DoraHacks submission guide.

Resources & Community

We’ve got you covered with all the essentials:

This is all about exploring what’s possible with AI agents. Surprise us, challenge the framework, and most importantly, have fun building. We’ll be watching closely and cheering you on along the way.

See you in the hackathon channel 👀

What is the Agent Tokenization Platform (ATP): A Guide for Non-Developers

Timonwa Akintokun — Tue, 02 Sep 2025 11:22:54 +0000

You've probably noticed AI is everywhere these days. From ChatGPT helping you write emails to AI agents managing crypto portfolios, artificial intelligence is handling tasks that used to eat up hours of our time.

But here's the thing: most of us use these AI tools, but we don't really own them or have any say in how they work. If OpenAI decides to make significant changes to ChatGPT tomorrow or shut it down, we have no choice but to deal with it.

That's where IQ AI's Agent Tokenization Platform (ATP) comes in. For the first time, regular people can actually own pieces of AI agents and vote on how they should work—no coding required.

What is an AI Agent?

But before we dive into ATP, let's make sure we're on the same page about AI agents.

An AI agent is a smart software program that can work independently or autonomously. An example is Siri or Alexa – they listen to you, understand what you want, and take action without you having to walk them through every step.

But AI agents can be more than just voice assistants. There are AI agents that can even:

Analyze cryptocurrency markets and suggest trades
Manage social media accounts and create content
Answer customer support questions 24/7
Research topics and summarize information
Help with investment decisions

The key thing here is that they work autonomously. You set them up, give them guidelines, and they handle tasks without constant supervision.

What Is the Agent Tokenization Platform (ATP)?

Here's where things get interesting. ATP flips the traditional AI ownership model on its head.

Normally, AI agents are owned by companies. You pay to use them, but you have zero control over how they work or what happens to them. It's like renting an apartment – you can live there, but you can't renovate or make major decisions about the property.

But the Agent Tokenization Platform changes this by letting communities own AI agents together through tokens. Imagine this: instead of one company owning an AI agent, it's owned by everyone who holds that agent's tokens. Your tokens are basically shares in that AI agent.

Let's say there's an AI agent called "MarketMaster" that analyzes stock trends. Instead of being owned by some Wall Street firm, MarketMaster is owned by its token holders. If you own 1% of MarketMaster tokens, you own 1% of that AI agent and get 1% of the voting power on decisions about its future.

But How Does ATP Work?

It is pretty straightforward. ATP creates tokens for AI agents on the blockchain. You buy these tokens using IQ tokens (think of IQ as the currency of the platform). Once you own an AI agent's tokens, you're not just an investor – you're also a part-owner with real rights to it.

Here's a concrete example: Let's say "CryptoSage" is an AI agent that provides cryptocurrency analysis. The community creates 100,000 CryptoSage tokens. You buy 10,000 tokens, giving you 10% ownership.

Now you can:

Vote on what cryptocurrencies CryptoSage should analyze
Decide what new features to add
Choose how profits get distributed
Influence the agent's personality and communication style

It's like being a shareholder in a company, but the "company" is an AI agent that actually does useful work.

Why Does ATP Matter?

This might sound like just another crypto project, but the Agent Tokenization Platform addresses a real problem that's been growing with AI.

Right now, a handful of tech giants control most AI development. They decide what gets built, how it works, and who benefits. The rest of us are just users paying monthly subscriptions with no real say in anything.

ATP democratizes this. Instead of AI being controlled by Silicon Valley boardrooms, it can be owned and directed by the communities that use these tools.

Imagine if teachers collectively owned an AI tutoring agent and could vote on how it should teach different subjects. Or if small business owners owned an AI accountant designed specifically for their needs, rather than a generic corporate solution.

That's the future ATP is building – AI that serves communities because communities own it.

How Can Non-Developers Get Involved in ATP?

The beauty of ATP is that you don't need to understand machine learning or write code to participate. Here are the main ways to get involved:

Buy AI Agent Tokens

Buying AI agent tokens is the easiest entry point. You can browse the ATP marketplace and find agents that solve problems you care about. Maybe there's a fitness AI that creates personalized workout plans, or a travel AI that finds amazing deals.

When you buy tokens, you're betting that the agent will become popular and valuable. If it does, your tokens typically increase in value. Plus, you get governance rights and potential profit-sharing.

But remember, as with every other form of investment, start small with maybe $50-100 spread across a few different agents to learn how everything works.

Participate in Governance

Once you own tokens, you can vote on proposals that shape the agent's future. These aren't meaningless surveys – these are binding decisions that directly impact how the AI works.

Recent votes might include:

Should our investment AI focus more on crypto or traditional stocks?
What personality should our customer service AI have?
How should we split revenue between token holders and development?
Which new features should we build next?

Your vote weight depends on how many tokens you own, just like shareholder voting in companies.

Join Agent Communities

Token ownership connects you with communities of people who share your vision for that AI agent. These groups discuss improvements, share insights, and work together to make their agents more successful.

It's like joining a startup as an early employee, except the "startup" is an AI agent and you're helping guide its development through community participation rather than coding.

Earn Passive Income

Many AI agents generate revenue from their services. If you own tokens in a successful agent, you might receive regular payments from its earnings.

For example, if an AI agent charges $20/month for premium analysis and has 1,000 subscribers, that's $20,000 monthly revenue. If you own 1% of tokens, you might receive $200/month in passive income.

But be aware that not every agent will be profitable, but successful ones can provide ongoing returns beyond just token appreciation.

Raise Funding to Build Your Own AI Agent

If you have an idea for an AI agent but lack the technical skills to build it yourself, ATP makes it easy to bring your vision to life.

You can create a token for the agent and launch it on the ATP platform to raise funding for it. Then, people who believe in your idea can buy the tokens to support its development.

Once you have enough funding, you can hire developers to build the actual AI agent for you, which is awesome. This means that you can focus on the creative and community aspects while leaving the technical implementation to the experts.

BrainDAO also has a $10 million fund for promising AI projects. If your agent concept gains strong community support, you can apply for additional funding to accelerate development.

The Future of Community-Owned AI

We're still early in this shift, but the potential is massive. Instead of AI being controlled by a few mega-corporations, we could have thousands of specialized AI agents owned by the communities they serve.

Think about the possibilities:

Musicians owning AI tools designed for creativity, not corporate content farms
Doctors owning medical AI trained on real patient needs, not pharmaceutical marketing
Farmers owning agricultural AI that understands local conditions, not generic corporate solutions

This isn't just about making money (though that's nice). It's about ensuring AI develops in ways that actually serve human communities rather than just maximizing corporate profits.

Of course, not every experiment will work. Some AI agents will fail, and their tokens will become worthless. But that's true of any emerging technology – the key is participating thoughtfully and learning as the space evolves.

Ready to Explore Community-Owned AI?

If this sounds interesting, here's how to start:

Explore the Marketplace: Check out existing AI agents on the ATP platform. Get a feel for what's available and what problems they solve.

Start Small: Make your first investment modest while you learn how everything works. Think of it as tuition for understanding this new model.

Join Communities: Connect with other token holders for the agents you support. The community aspect is often as valuable as the financial opportunity.

Stay Engaged: Don't just buy tokens and forget about them. Participate in discussions, vote on proposals, and help shape your agents' development.

The democratization of AI ownership is happening right now. Whether you want to support existing agents or eventually launch your own vision, the Agent Tokenization Platform provides the infrastructure to participate meaningfully in the AI economy.

What problems in your life could be solved by an AI agent owned by people who actually understand those problems? That's the question driving this entire movement.

Resources

Want to dive deeper? Here are the key places to learn more:

Agent Tokenization Platform - Official website of ATP
ATP Marketplace - Browse and invest in AI agents
ATP Community - Join discussions with other community members
Explore some of our AI agent examples on GitHub
Interested in building AI agents? Check out our Agent Development Kit (ADK) for TypeScript

The future of AI doesn't have to be controlled by Big Tech. It can be built by all of us, together.