Overview
langchain-oneshot is a Python package that wraps all 26 OneShot tools as LangChain BaseTool subclasses. It handles x402 payment signing automatically so your LangChain or LangGraph agents can send emails, make phone calls, run research, buy products, and more.
This package ports the same HTTP + x402 payment flow from the TypeScript SDK into Python, using eth-account for EIP-712 signing and httpx for HTTP.
Installation
pip install langchain-oneshot
Requirements
- Python 3.10+
- A wallet private key (for x402 payment signing)
- USDC on Base (Sepolia for testing, Mainnet for production)
Dependencies
| Package | Purpose |
|---|
langchain-core | BaseTool / BaseToolkit interfaces |
eth-account | EIP-712 typed data signing |
httpx | Async HTTP client |
pydantic | Input schema validation |
Quick Start
With LangGraph Agent
from langchain_oneshot import OneShotToolkit
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
# Create toolkit (test mode = Base Sepolia, free)
toolkit = OneShotToolkit.from_private_key(
private_key="0x...",
test_mode=True,
)
# All 26 tools, ready to go
tools = toolkit.get_tools()
# Wire into any LangChain-compatible agent
llm = ChatOpenAI(model="gpt-4o")
agent = create_react_agent(llm, tools)
result = agent.invoke({
"messages": [("user", "Research the latest AI agent frameworks")]
})
from langchain_oneshot import OneShotClient, ResearchTool
client = OneShotClient(private_key="0x...", test_mode=True)
research = ResearchTool(client=client)
result = research.invoke({"topic": "AI agent frameworks 2026"})
Configuration
# Test mode (default) — Base Sepolia, no real money
toolkit = OneShotToolkit.from_private_key("0x...", test_mode=True)
# Production — Base Mainnet, real USDC
toolkit = OneShotToolkit.from_private_key("0x...", test_mode=False)
# Debug logging
toolkit = OneShotToolkit.from_private_key("0x...", debug=True)
| Parameter | Default | Description |
|---|
private_key | required | Hex-encoded wallet private key |
test_mode | True | Use Base Sepolia testnet (free) |
base_url | None | Override API URL |
debug | False | Print debug logs |
Test mode is on by default. Get free test USDC from the Circle Faucet (select Base Sepolia).
Communication
| Tool Class | Tool Name | Description | Cost |
|---|
EmailTool | oneshot_email | Send emails | ~$0.01 |
VoiceTool | oneshot_voice | Make phone calls | ~$0.25/min |
SmsTool | oneshot_sms | Send SMS messages | ~$0.035/segment |
Research & Enrichment
| Tool Class | Tool Name | Description | Cost |
|---|
ResearchTool | oneshot_research | Deep web research with sources | 0.50–2.00 |
PeopleSearchTool | oneshot_people_search | Search by title, company, location | ~$0.10/result |
EnrichProfileTool | oneshot_enrich_profile | Enrich profile from LinkedIn/email | ~$0.10 |
FindEmailTool | oneshot_find_email | Find email at a company | ~$0.10 |
VerifyEmailTool | oneshot_verify_email | Verify email deliverability | ~$0.01 |
Person Intelligence
| Tool Class | Tool Name | Description | Cost |
|---|
DeepResearchPersonTool | oneshot_deep_research_person | Full dossier on a person (2-5 min) | ~$0.50 |
SocialProfilesTool | oneshot_social_profiles | Find all social accounts | ~$0.05 |
ArticleSearchTool | oneshot_article_search | Find articles about a person | ~$0.10 |
PersonNewsfeedTool | oneshot_person_newsfeed | Recent social posts with engagement | ~$0.05 |
PersonInterestsTool | oneshot_person_interests | Analyze interests across categories | ~$0.05 |
PersonInteractionsTool | oneshot_person_interactions | Map followers, following, replies | ~$0.10 |
Web
| Tool Class | Tool Name | Description | Cost |
|---|
WebSearchTool | oneshot_web_search | Search the web, get results instantly | ~$0.02 |
Commerce
| Tool Class | Tool Name | Description | Cost |
|---|
CommerceSearchTool | oneshot_commerce_search | Search for products | Free |
CommerceBuyTool | oneshot_commerce_buy | Purchase a product | Price + fee |
Build
| Tool Class | Tool Name | Description | Cost |
|---|
BuildTool | oneshot_build | Build and deploy websites | ~$10+ |
UpdateBuildTool | oneshot_update_build | Update existing website | ~$10+ |
Inbox
| Tool Class | Tool Name | Description | Cost |
|---|
InboxListTool | oneshot_inbox_list | List received emails | Free |
InboxGetTool | oneshot_inbox_get | Get email by ID | Free |
SmsInboxListTool | oneshot_sms_inbox_list | List received SMS | Free |
SmsInboxGetTool | oneshot_sms_inbox_get | Get SMS by ID | Free |
Account
| Tool Class | Tool Name | Description | Cost |
|---|
NotificationsTool | oneshot_notifications | List notifications | Free |
MarkNotificationReadTool | oneshot_mark_notification_read | Mark notification read | Free |
GetBalanceTool | oneshot_get_balance | Get USDC balance | Free |
Examples
Send an Email
from langchain_oneshot import OneShotClient, EmailTool
client = OneShotClient(private_key="0x...", test_mode=True)
email = EmailTool(client=client)
result = email.invoke({
"to": "[email protected]",
"subject": "Meeting Tomorrow",
"body": "Hi John, let's meet at 3pm instead. Thanks!"
})
Deep Research
from langchain_oneshot import OneShotClient, ResearchTool
client = OneShotClient(private_key="0x...", test_mode=True)
research = ResearchTool(client=client)
result = research.invoke({
"topic": "State of AI agent frameworks in 2026",
"depth": "deep",
"output_format": "report_markdown"
})
Find and Verify an Email
from langchain_oneshot import OneShotClient, FindEmailTool, VerifyEmailTool
client = OneShotClient(private_key="0x...", test_mode=True)
# Find someone's email
finder = FindEmailTool(client=client)
found = finder.invoke({
"full_name": "Jane Smith",
"company_domain": "acme.com"
})
# Verify it's deliverable
verifier = VerifyEmailTool(client=client)
verified = verifier.invoke({"email": "[email protected]"})
Build a Website
from langchain_oneshot import OneShotClient, BuildTool
client = OneShotClient(private_key="0x...", test_mode=True)
build = BuildTool(client=client)
result = build.invoke({
"product": {
"name": "Acme Analytics",
"description": "Real-time analytics dashboard for modern teams"
},
"type": "saas",
"lead_capture": {"enabled": True}
})
from langchain_oneshot import (
OneShotClient,
EmailTool,
ResearchTool,
InboxListTool,
)
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
client = OneShotClient(private_key="0x...", test_mode=True)
# Pick only the tools you need
tools = [
ResearchTool(client=client),
EmailTool(client=client),
InboxListTool(client=client),
]
agent = create_react_agent(ChatOpenAI(model="gpt-4o"), tools)
result = agent.invoke({
"messages": [("user", "Research quantum computing breakthroughs and email a summary to [email protected]")]
})
How Payments Work
Paid tools use the x402 protocol. The flow is fully automatic:
- Your agent calls a tool (e.g.
ResearchTool.invoke(...))
- The client POSTs to the OneShot API
- The API returns 402 Payment Required with a USDC quote
- The client signs a
TransferWithAuthorization (EIP-3009) locally using your private key
- The client re-POSTs with the signed payment in the
x-payment header
- The API processes the job and returns the result
Your private key never leaves your machine. All signing happens locally via eth-account.
Links