langchain-x402

LangChain tools for x402 Engine — pay-per-call AI, crypto, and storage APIs via HTTP 402 micropayments.

Give your LangChain agents the ability to generate images, execute code, transcribe audio, look up crypto prices, analyze wallets, and pin data to IPFS — all paid with stablecoins (USDC on Base/Solana, USDm on MegaETH).

Install

npm install langchain-x402 @langchain/core

Quick Start

import { createX402Tools } from "langchain-x402";

// Create all tools with shared config
const tools = createX402Tools({
  paymentHeader: process.env.X402_PAYMENT_HEADER,
});

// Or import individual tools
import { GenerateImageTool, CryptoPriceTool } from "langchain-x402";

const imageTool = new GenerateImageTool();
const priceTool = new CryptoPriceTool();

With a LangChain Agent

import { ChatOpenAI } from "@langchain/openai";
import { createToolCallingAgent, AgentExecutor } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { createX402Tools } from "langchain-x402";

const llm = new ChatOpenAI({ model: "gpt-4o" });
const tools = createX402Tools();

const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are a helpful assistant with access to x402 Engine APIs."],
  ["human", "{input}"],
  ["placeholder", "{agent_scratchpad}"],
]);

const agent = createToolCallingAgent({ llm, tools, prompt });
const executor = new AgentExecutor({ agent, tools });

const result = await executor.invoke({
  input: "What's the current price of Bitcoin and Ethereum?",
});

Configuration

Tools accept an optional config object and/or read from environment variables:

Config Key	Env Variable	Description
baseUrl	X402_BASE_URL	Gateway URL (default: https://x402engine.app)
paymentHeader	X402_PAYMENT_HEADER	Pre-signed X-PAYMENT header for x402
devBypass	X402_DEV_BYPASS	Dev bypass token to skip payment

Available Tools

Compute

Tool	Description	Price
GenerateImageTool	AI image generation (fast/quality/text tiers)	$0.015-$0.12
ExecuteCodeTool	Sandboxed code execution (Python, JS, Bash, R)	$0.005
TranscribeAudioTool	Audio-to-text transcription (Deepgram Nova-3)	$0.10

Crypto Data

Tool	Description	Price
CryptoPriceTool	Real-time cryptocurrency prices	$0.001
CryptoMarketsTool	Market rankings with detailed data	$0.002
CryptoHistoryTool	Historical price/volume/mcap data	$0.003
TrendingCryptoTool	Currently trending coins	$0.001
CryptoSearchTool	Search coins by name or symbol	$0.001

Blockchain Analytics

Tool	Description	Price
WalletBalancesTool	Token balances across 20+ chains	$0.005
WalletTransactionsTool	Transaction history with labels	$0.005
WalletPnlTool	Portfolio profit/loss analysis	$0.01
TokenPricesTool	DEX-derived token prices (up to 200/req)	$0.005
TokenMetadataTool	Token metadata (name, symbol, decimals)	$0.002

Storage

Tool	Description	Price
PinJsonToIpfsTool	Pin JSON to IPFS, returns CID	$0.01
GetFromIpfsTool	Retrieve content from IPFS by CID	$0.001

How x402 Payment Works

x402 is an open protocol for HTTP-native micropayments. When a tool makes a request:

1. If no payment header is configured, the API returns HTTP 402 with payment requirements
2. The tool returns the payment details so your agent (or a higher-level system) can handle payment
3. With a valid X-PAYMENT header, the request succeeds and the API responds normally

For automatic payment handling, use @x402/client to generate payment headers from a wallet.

Payment Networks

Network	Stablecoin	Confirmation
Base	USDC	~2s
Solana	USDC	~400ms
MegaETH	USDm	~10ms

Extending

All tools extend X402BaseTool, which itself extends LangChain's StructuredTool. You can create custom tools by extending the base class:

import { z } from "zod";
import { X402BaseTool } from "langchain-x402";

class MyCustomTool extends X402BaseTool {
  name = "my_custom_tool";
  description = "My custom x402 tool";
  schema = z.object({ input: z.string() });

  async _call(input: { input: string }) {
    const res = await this.callApi("POST", "/api/my-endpoint", undefined, input);
    return this.formatResult(res);
  }
}

Links

• x402 Engine — API gateway
• x402 Protocol — Payment protocol spec
• MCP Server — Model Context Protocol server
• GitHub

License

MIT