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