langchain-oneshot

LangChain tools for OneShot: 52 tools plus additional tools from the lookup manifest, as LangChain BaseTool subclasses. Your agent sends email, makes calls, researches, enriches, and buys; each paid call is paid automatically in USDC on Base (x402).

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 the tools (49, plus additional tools from the lookup manifest) 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 pay from prepaid credits and never hold 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 within its stored caps and 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. Current rates are on the Pricing page.

How Payments Work

Payment signing happens locally; your private key never leaves your machine. 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

Read tools (inbox, SMS inbox, notifications, balance, browser profiles) also 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. The underlying oneshot-python client handles this with no extra code. It requires oneshot-python >= 0.18.0, which is 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 runs 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",
)

The server enforces the budget 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.

LinkedIn connection recovery

If the active account list is empty or an account is connection_deleted or revoked, ask the human to use oneshot_linkedin_connect and authorize fresh grants. An existing account with reconnect_required must be reconnected through the owning application. Reconnect and revoke are deliberately not agent tools. Do not create a new connection automatically after authentication failures or timeouts.

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

Optional phone lookup

person_find, person_profile, and person_dossier accept include_phone, off by default. It adds the per-person add-on listed on the pricing page × the requested search limit (default 100) for a search, or once for profile/dossier, for up to that many people with no promised hit. Existing source numbers and published business or record numbers remain available without opting in. Fallbacks and callbacks cost nothing extra; a completed no-match is charged and a failed job is refunded. Use a boolean true / false. The full quote is checked before payment.

Solve

Plan vehicle routes, pack items into bins, or schedule jobs on resources, returning constraint checks and conflicts. Use oneshot_solve with problem: "routing" and a routing block containing vehicles, stops and an objective, problem: "packing" and a packing block containing variant (bin or knapsack), dimensions, bins and items, or problem: "schedule" and a schedule block containing jobs, resources and an objective. Provide only the block matching the selected problem.

See Solve for input examples, results and limits.

Predict

Use PredictTool(client=client) or the toolkit’s oneshot_predict tool. Supports model: "simulation" with a simulation block of named distributions and arithmetic outputs, or model: "forecast" with a forecast block containing a time series and horizon. Returns uncertainty ranges and consistency checks.

See Predict for inputs, results and limits.