langchain-pr402

LangChain tools for autonomous AI agent payments on Solana via the pr402/x402 protocol.

Give any LangChain agent a Solana wallet so it can autonomously pay for HTTP services that return 402 Payment Required.

Installation

pip install langchain-pr402

Quick Start

from langchain_pr402 import X402RequestsWrapper, X402GetTool, X402BalanceTool

# 1. Create a wrapper with your agent's Solana keypair (defaults to Devnet)
wrapper = X402RequestsWrapper(
    keypair_bytes=[1, 2, 3, ...],  # 64-byte Solana keypair as list of ints
    # rpc_url defaults to "https://api.devnet.solana.com"
    # default_facilitator_url defaults to "https://preview.ipay.sh" (Devnet)
)

# 2. Create tools and give them to your agent
tools = [
    X402GetTool(requests_wrapper=wrapper),
    X402BalanceTool(requests_wrapper=wrapper),
]

# 3. Use with any LangChain agent (GPT-4, Claude, Llama, etc.)
from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor

llm = ChatOpenAI(model="gpt-4o-mini")
agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)
executor.invoke({"input": "Check my wallet balance"})

How It Works

1. Your agent calls X402GetTool to fetch a URL.
2. If the server responds with HTTP 402 Payment Required, the tool automatically:
   • Parses the payment terms from the Payment-Required header
   • Builds a Solana transaction via the pr402 facilitator (Devnet by default)
   • Signs the transaction locally with the agent's keypair
   • Retries the request with a PAYMENT-SIGNATURE header
3. The agent receives the paid content — the LLM never sees the payment complexity.

Tools

Setting Up the Agent Wallet

AI agents don't create their own wallets. The developer provisions one:

1. Create a wallet: solana-keygen new -o agent-keypair.json
2. Fund it: Send USDC and a small amount of SOL for transaction fees
3. Configure: Pass the keypair bytes to X402RequestsWrapper

# Via environment variable (recommended for production)
export SOLANA_PRIVATE_KEY='[1,2,3,...,64]'

import os, json
wrapper = X402RequestsWrapper(
    keypair_bytes=json.loads(os.environ["SOLANA_PRIVATE_KEY"])
)

Networks

By default, the wrapper is configured for Solana Devnet (great for testing). To switch to Mainnet, override both URLs:

wrapper = X402RequestsWrapper(
    keypair_bytes=json.loads(os.environ["SOLANA_PRIVATE_KEY"]),
    rpc_url="https://api.mainnet-beta.solana.com",
    default_facilitator_url="https://ipay.sh",  # Mainnet facilitator
)

Security

• Private key material is never serialised — keypair_bytes is excluded from model_dump(), repr(), and logging.
• The wrapper signs transactions locally. Private keys never leave the machine.
• The pr402 facilitator only receives the public key and returns an unsigned transaction.

Links

• pr402/x402 Protocol
• pr402 Facilitator
• Documentation