LangChain

Give a LangChain agent two tools: a free lookup (best match + top 3) and a paid full ranking it can use when the free answer is not enough. The paid tool calls route_paid() from paid_client.py, which uses the official x402 Python client.

pip install langchain "x402[httpx,evm]" httpx   # plus your model provider, e.g. langchain-anthropic
export EVM_PRIVATE_KEY=0x...   # wallet with a little USDC on Base
# LangChain tool for X402 Router. pip install langchain "x402[httpx,evm]" httpx   (+ your model's provider package)
# Put paid_client.py (from /examples) next to this file.
import httpx
from langchain_core.tools import tool
from paid_client import ROUTER, route_paid

@tool
def find_x402_api_free(task: str, chain: str = "Base") -> dict:
    """Free: best live x402 (pay-per-call) API for a task, plus the top 3 matches with prices."""
    return httpx.post(f"{ROUTER}/route", json={"q": task, "chain": chain}, timeout=30).json()

@tool
async def find_x402_api_ranked(task: str, chain: str = "Base", max_price: float = 0.05) -> dict:
    """Paid, 0.01 USDC: full ranked list (up to 25) of live x402 APIs for a task with latency, reliability,
    price and payTo, plus a ready-to-pay best pick. Use when the free top 3 is not enough."""
    return await route_paid(task, chain, max_price)

# from langchain.agents import create_agent
# agent = create_agent(model="claude-sonnet-4-6", tools=[find_x402_api_free, find_x402_api_ranked])
# result = await agent.ainvoke({"messages": [{"role": "user", "content": "Find a working weather API I can pay per call on Base"}]})

Free trial: 3 free trial calls per wallet per day, no payment needed. Add the header X-402-Trial: <your wallet address> (EVM 0x… or Solana) to /route/paid and you get the same full ranked answer a paid call gets. Limits: 3 per wallet and 3 per IP per UTC day, from a shared pool of 100 a day. After that you get the normal 402. Try it · trial.sh · trial_call.py

Download langchain_tool.py

Tool docstrings become the tool descriptions the model sees, so keep the price in them: agents then only pay when they need the full ranking.

Test status (17 Nov 2026): langchain-core 1.8.1: both functions load as StructuredTool, and find_x402_api_ranked.ainvoke() was run against a local replay of the router's live unsigned 402 (exact captured PAYMENT-REQUIRED header and body); the client produced a valid x402 v2 payment for 0.01 USDC (amount 10000) on eip155:8453 to the router's payTo. The signed payment was captured locally and never sent, so no funds moved. The create_agent lines follow LangChain's current docs and were not executed (they need a model API key).

Prices: /route/paid 0.01 USDC, /check/paid 0.002 USDC, /route free. x402 v2 on Base (eip155:8453) or Solana. Machine-readable: OpenAPI · /.well-known/x402 · llms.txt