Building AI Agents That Interact With Blockchain: A Deep Technical Guide Using LangChain

mkdir ai-blockchain-agent && cd ai-blockchain-agent
npm init -y
npm install langchain @langchain/openai @langchain/core ethers dotenv
npm install -D typescript ts-node @types/node hardhat
npx tsc --init

OPENAI_API_KEY=your_openai_key
ALCHEMY_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your_key
PRIVATE_KEY=your_wallet_private_key

// src/provider.ts
import { ethers } from "ethers";
import * as dotenv from "dotenv";
dotenv.config();

export const provider = new ethers.JsonRpcProvider(process.env.ALCHEMY_RPC_URL);

export const signer = new ethers.Wallet(
  process.env.PRIVATE_KEY!,
  provider
);

// src/tools/getBalance.ts
import { DynamicTool } from "@langchain/core/tools";
import { provider } from "../provider";
import { ethers } from "ethers";

export const getBalanceTool = new DynamicTool({
  name: "get_eth_balance",
  description:
    "Get the ETH balance of a wallet address. Input should be a valid Ethereum address.",
  func: async (address: string) => {
    try {
      const balance = await provider.getBalance(address);
      return `Balance: ${ethers.formatEther(balance)} ETH`;
    } catch (err) {
      return `Error fetching balance: ${err}`;
    }
  },
});

// src/tools/getTokenBalance.ts
import { DynamicStructuredTool } from "@langchain/core/tools";
import { z } from "zod";
import { ethers } from "ethers";
import { provider } from "../provider";

const ERC20_ABI = [
  "function balanceOf(address owner) view returns (uint256)",
  "function decimals() view returns (uint8)",
  "function symbol() view returns (string)",
];

export const getTokenBalanceTool = new DynamicStructuredTool({
  name: "get_token_balance",
  description:
    "Get the ERC-20 token balance for a wallet. Provide the token contract address and wallet address.",
  schema: z.object({
    tokenAddress: z.string().describe("ERC-20 token contract address"),
    walletAddress: z.string().describe("Wallet address to check"),
  }),
  func: async ({ tokenAddress, walletAddress }) => {
    try {
      const contract = new ethers.Contract(tokenAddress, ERC20_ABI, provider);
      const [balance, decimals, symbol] = await Promise.all([
        contract.balanceOf(walletAddress),
        contract.decimals(),
        contract.symbol(),
      ]);
      const formatted = ethers.formatUnits(balance, decimals);
      return `${formatted} ${symbol}`;
    } catch (err) {
      return `Error: ${err}`;
    }
  },
});

// src/tools/readContract.ts
import { DynamicStructuredTool } from "@langchain/core/tools";
import { z } from "zod";
import { ethers } from "ethers";
import { provider } from "../provider";

export const readContractTool = new DynamicStructuredTool({
  name: "read_contract",
  description:
    "Call a read-only function on any smart contract. Provide the contract address, ABI as a JSON string, function name, and arguments array.",
  schema: z.object({
    contractAddress: z.string(),
    abi: z.string().describe("JSON string of the contract ABI"),
    functionName: z.string(),
    args: z.array(z.string()).default([]),
  }),
  func: async ({ contractAddress, abi, functionName, args }) => {
    try {
      const parsedAbi = JSON.parse(abi);
      const contract = new ethers.Contract(contractAddress, parsedAbi, provider);
      const result = await contract[functionName](...args);
      return `Result: ${result.toString()}`;
    } catch (err) {
      return `Error: ${err}`;
    }
  },
});

// src/tools/getGasPrice.ts
import { DynamicTool } from "@langchain/core/tools";
import { provider } from "../provider";
import { ethers } from "ethers";

export const getGasPriceTool = new DynamicTool({
  name: "get_gas_price",
  description: "Get the current gas price on Ethereum mainnet in Gwei.",
  func: async () => {
    try {
      const feeData = await provider.getFeeData();
      const gasPriceGwei = ethers.formatUnits(feeData.gasPrice!, "gwei");
      const maxFeeGwei = ethers.formatUnits(feeData.maxFeePerGas!, "gwei");
      return `Base gas price: ${parseFloat(gasPriceGwei).toFixed(2)} Gwei | Max fee: ${parseFloat(maxFeeGwei).toFixed(2)} Gwei`;
    } catch (err) {
      return `Error: ${err}`;
    }
  },
});

// src/tools/getSwapQuote.ts
import { DynamicStructuredTool } from "@langchain/core/tools";
import { z } from "zod";
import { ethers } from "ethers";
import { provider } from "../provider";

// Uniswap V3 Quoter contract on mainnet
const QUOTER_ADDRESS = "0xb27308f9F90D607463bb33eA1BeBb41C27CE5AB6";
const QUOTER_ABI = [
  "function quoteExactInputSingle(address tokenIn, address tokenOut, uint24 fee, uint256 amountIn, uint160 sqrtPriceLimitX96) external returns (uint256 amountOut)",
];

export const getSwapQuoteTool = new DynamicStructuredTool({
  name: "get_swap_quote",
  description:
    "Get a Uniswap V3 swap quote. Returns how many tokens you'd receive for a given input amount.",
  schema: z.object({
    tokenIn: z.string().describe("Input token contract address"),
    tokenOut: z.string().describe("Output token contract address"),
    fee: z.number().describe("Pool fee tier: 500, 3000, or 10000"),
    amountIn: z.string().describe("Amount in (human-readable, e.g. '1.5')"),
    decimalsIn: z.number().default(18),
    decimalsOut: z.number().default(18),
  }),
  func: async ({ tokenIn, tokenOut, fee, amountIn, decimalsIn, decimalsOut }) => {
    try {
      const quoter = new ethers.Contract(QUOTER_ADDRESS, QUOTER_ABI, provider);
      const amountInWei = ethers.parseUnits(amountIn, decimalsIn);
      const amountOut = await quoter.quoteExactInputSingle.staticCall(
        tokenIn,
        tokenOut,
        fee,
        amountInWei,
        0
      );
      const formatted = ethers.formatUnits(amountOut, decimalsOut);
      return `You would receive approximately ${formatted} tokens for ${amountIn} input tokens.`;
    } catch (err) {
      return `Error getting quote: ${err}`;
    }
  },
});

// src/agent.ts
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIFunctionsAgent } from "langchain/agents";
import { ChatPromptTemplate, MessagesPlaceholder } from "@langchain/core/prompts";
import { BufferMemory } from "langchain/memory";

import { getBalanceTool } from "./tools/getBalance";
import { getTokenBalanceTool } from "./tools/getTokenBalance";
import { readContractTool } from "./tools/readContract";
import { getGasPriceTool } from "./tools/getGasPrice";
import { getSwapQuoteTool } from "./tools/getSwapQuote";

const tools = [
  getBalanceTool,
  getTokenBalanceTool,
  readContractTool,
  getGasPriceTool,
  getSwapQuoteTool,
];

const llm = new ChatOpenAI({
  modelName: "gpt-4o",
  temperature: 0,
  openAIApiKey: process.env.OPENAI_API_KEY,
});

const prompt = ChatPromptTemplate.fromMessages([
  [
    "system",
    `You are a DeFi-native AI agent with direct access to the Ethereum blockchain.
You can read wallet balances, token holdings, smart contract state, gas prices, and DEX swap quotes.
Always verify addresses before acting. When providing numbers, format them clearly with appropriate units.
Never guess on-chain data — always use your tools to fetch it.
If a user asks you to perform a transaction, confirm all parameters before proceeding.`,
  ],
  new MessagesPlaceholder("chat_history"),
  ["human", "{input}"],
  new MessagesPlaceholder("agent_scratchpad"),
]);

const memory = new BufferMemory({
  memoryKey: "chat_history",
  returnMessages: true,
});

export async function createBlockchainAgent() {
  const agent = await createOpenAIFunctionsAgent({ llm, tools, prompt });

  return new AgentExecutor({
    agent,
    tools,
    memory,
    verbose: true,
    maxIterations: 10,
  });
}

// src/index.ts
import { createBlockchainAgent } from "./agent";
import * as dotenv from "dotenv";
dotenv.config();

async function main() {
  const agent = await createBlockchainAgent();

  const queries = [
    "What is the ETH balance of 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?",
    "What's the current gas price on Ethereum?",
    "How much USDC would I get if I swap 1 ETH on Uniswap V3? USDC address is 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48, WETH is 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2, use the 500 fee tier.",
  ];

  for (const query of queries) {
    console.log(`\n🧠 Query: ${query}`);
    const result = await agent.invoke({ input: query });
    console.log(`✅ Response: ${result.output}`);
  }
}

main().catch(console.error);