Skip to main content

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

PackagePurpose
langchain-coreBaseTool / BaseToolkit interfaces
eth-accountEIP-712 typed data signing
httpxAsync HTTP client
pydanticInput 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")]
})

Individual Tools

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)
ParameterDefaultDescription
private_keyrequiredHex-encoded wallet private key
test_modeTrueUse Base Sepolia testnet (free)
base_urlNoneOverride API URL
debugFalsePrint debug logs
Test mode is on by default. Get free test USDC from the Circle Faucet (select Base Sepolia).

Available Tools

Communication

Tool ClassTool NameDescriptionCost
EmailTooloneshot_emailSend emails~$0.01
VoiceTooloneshot_voiceMake phone calls~$0.25/min
SmsTooloneshot_smsSend SMS messages~$0.035/segment

Research & Enrichment

Tool ClassTool NameDescriptionCost
ResearchTooloneshot_researchDeep web research with sources0.500.50–2.00
PeopleSearchTooloneshot_people_searchSearch by title, company, location~$0.10/result
EnrichProfileTooloneshot_enrich_profileEnrich profile from LinkedIn/email~$0.10
FindEmailTooloneshot_find_emailFind email at a company~$0.10
VerifyEmailTooloneshot_verify_emailVerify email deliverability~$0.01

Person Intelligence

Tool ClassTool NameDescriptionCost
DeepResearchPersonTooloneshot_deep_research_personFull dossier on a person (2-5 min)~$0.50
SocialProfilesTooloneshot_social_profilesFind all social accounts~$0.05
ArticleSearchTooloneshot_article_searchFind articles about a person~$0.10
PersonNewsfeedTooloneshot_person_newsfeedRecent social posts with engagement~$0.05
PersonInterestsTooloneshot_person_interestsAnalyze interests across categories~$0.05
PersonInteractionsTooloneshot_person_interactionsMap followers, following, replies~$0.10

Web

Tool ClassTool NameDescriptionCost
WebSearchTooloneshot_web_searchSearch the web, get results instantly~$0.02

Commerce

Tool ClassTool NameDescriptionCost
CommerceSearchTooloneshot_commerce_searchSearch for productsFree
CommerceBuyTooloneshot_commerce_buyPurchase a productPrice + fee

Build

Tool ClassTool NameDescriptionCost
BuildTooloneshot_buildBuild and deploy websites~$10+
UpdateBuildTooloneshot_update_buildUpdate existing website~$10+

Inbox

Tool ClassTool NameDescriptionCost
InboxListTooloneshot_inbox_listList received emailsFree
InboxGetTooloneshot_inbox_getGet email by IDFree
SmsInboxListTooloneshot_sms_inbox_listList received SMSFree
SmsInboxGetTooloneshot_sms_inbox_getGet SMS by IDFree

Account

Tool ClassTool NameDescriptionCost
NotificationsTooloneshot_notificationsList notificationsFree
MarkNotificationReadTooloneshot_mark_notification_readMark notification readFree
GetBalanceTooloneshot_get_balanceGet USDC balanceFree

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}
})

Full Agent with Selective Tools

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:
  1. Your agent calls a tool (e.g. ResearchTool.invoke(...))
  2. The client POSTs to the OneShot API
  3. The API returns 402 Payment Required with a USDC quote
  4. The client signs a TransferWithAuthorization (EIP-3009) locally using your private key
  5. The client re-POSTs with the signed payment in the x-payment header
  6. The API processes the job and returns the result
Your private key never leaves your machine. All signing happens locally via eth-account.