langchain-oneshot

LangChain tools for OneShot — commercial actions for AI agents.

Provides 43 tools as LangChain BaseTool subclasses with automatic x402 payment handling via USDC on Base.

Installation

pip install langchain-oneshot

Quick Start

from langchain_oneshot import OneShotToolkit
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

toolkit = OneShotToolkit.from_private_key(
    private_key="0x...",
)

# Use all 43 tools with a LangGraph agent
tools = toolkit.get_tools()
llm = ChatOpenAI(model="gpt-4o")
agent = create_react_agent(llm, tools)

result = agent.invoke({
    "messages": [("user", "Research the latest AI agent frameworks")]
})

Access-token sessions

Hosted agents can use prepaid credits without holding a wallet key:

import os
from langchain_oneshot import OneShotToolkit

toolkit = OneShotToolkit.from_access_token(os.environ["ONESHOT_ACCESS_TOKEN"])
# Inside an async application:
# toolkit = await OneShotToolkit.afrom_access_token(os.environ["ONESHOT_ACCESS_TOKEN"])
tools = toolkit.get_tools()

Mint the token and set budgets from a wallet session. Token calls spend the agent's credits and respect its stored caps; they cannot change budgets or manage tokens. An insufficient balance raises InsufficientCreditsError. Fund credits from a wallet with OneShotClient.top_up_credits(amount) and retry. See the hosted setup guide.

Individual Tools

from langchain_oneshot import OneShotClient, ResearchTool

client = OneShotClient(private_key="0x...")
research = ResearchTool(client=client)
result = research.invoke({"topic": "AI agent frameworks 2026"})

Available Tools

Paid tools are priced in USDC via x402. See Pricing for current rates.

How Payments Work

Paid tools use the x402 protocol. When a tool requires payment:

1. The client POSTs to the tool endpoint
2. The API returns 402 Payment Required with a quote
3. The client signs a USDC TransferWithAuthorization (EIP-3009) using your private key
4. The client re-POSTs with the signed payment header
5. The API processes the request and returns the result

All payment signing happens locally — your private key never leaves your machine.

Read tools (inbox, SMS inbox, notifications, balance, browser profiles) additionally send a signed EIP-712 read proof (x-agent-proof) so the API can verify you control the X-Agent-ID wallet before returning private data. This is handled by the underlying oneshot-python client — no extra code. Requires oneshot-python >= 0.18.0 (already the dependency floor).

Configuration

toolkit = OneShotToolkit.from_private_key("0x...")

# Custom API URL
toolkit = OneShotToolkit.from_private_key("0x...", base_url="https://custom-api.example.com")

The SDK operates on Base Mainnet with real USDC. Fund your wallet before making paid tool calls.

Spend budget

toolkit = OneShotToolkit.from_private_key(
    "0x...",
    budgets={"daily": 50, "per_transaction": 5, "alert_at": 0.8},
    alert_email="you@example.com",
)

Enforced server-side on every paid call (403 budget_exceeded → oneshot.BudgetExceededError). The agent can read its utilization with oneshot_budget_status but cannot change the cap. Requires oneshot-python >= 0.20.0.

Requirements

• Python 3.10+
• langchain-core >= 0.3.0
• oneshot-python >= 0.18.0
• pydantic >= 2.0

Links

• Documentation
• oneshot-python on PyPI — Core HTTP client (dependency)
• TypeScript SDK
• MCP Server
• GitHub

License

MIT

LinkedIn connection recovery

If the active account list is empty or an account is deleted_upstream or revoked, ask the human to use oneshot_linkedin_connect and authorize fresh grants. An existing account with reconnect_required needs reconnect through the owning application. Reconnect and revoke are intentionally not agent tools. Do not automatically create a new connection in response to authentication failures or timeouts.