Agent Adapters

bitpilot provides tool factories for three agent frameworks. By default they expose five read/propose tools. Pass agent_can_approve=True to also register approve_proposal for autonomous flows (still subject to policy and mainnet caps).

Exposed Tools

Tool	Type	Description
`get_balance`	Read-only	Current wallet balance
`get_utxos`	Read-only	List unspent transaction outputs
`estimate_fee`	Read-only	Fee rates from mempool.space
`propose_payment`	Write (gated)	Create a payment proposal (does NOT broadcast)
`list_proposals`	Read-only	List all proposals and their statuses

approve_proposal is opt-in via agent_can_approve=True on make_openai_tools, make_langchain_tools, and make_mcp_tools. reject_proposal is not exposed as a tool.

propose_payment and list_proposals responses include a policy object when a policy was evaluated: decision, code, reason, rule_name, and details (for LLM self-correction on limits).

OpenAI Agents SDK


from bitpilot import Wallet, FeeEstimator
from bitpilot.agent import make_openai_tools

wallet, _ = Wallet.create(network="testnet")
estimator = FeeEstimator(network="testnet")

tools = make_openai_tools(wallet, estimator)
# Pass to openai.chat.completions.create(tools=tools)

The OpenAIToolRegistry also provides dispatch(tool_name, arguments) for manual tool execution in agent loops.

Error Codes

Agent tool errors return structured JSON:


{"error": {"code": "WALLET_SYNC_ERROR", "message": "...", "details": {}}}

Codes include WALLET_SYNC_ERROR, WALLET_ERROR, MAINNET_CAP_EXCEEDED (with details.limit_sats / attempted_sats), INVALID_ARGUMENT, INTERNAL_ERROR.

Provider sync and fee estimation use bounded HTTP retries (429 / transient 5xx / timeouts) with backoff when calling public APIs.

LangChain


from bitpilot.agent import make_langchain_tools

tools = make_langchain_tools(wallet, estimator)
# Pass to create_tool_calling_agent(llm, tools, prompt)

Requires pip install bitpilot[agent]. Returns BaseTool subclass instances.

MCP (Model Context Protocol)


from bitpilot.agent import make_mcp_tools

server = make_mcp_tools(wallet, estimator)
tool_list = server.get_mcp_tool_list()
result = await server.call("get_balance", {})

The MCP adapter includes an additional get_runtime_status tool that reports backend readiness, sync availability, and network mode. For human-supervised IDE contexts, it also exposes approve_payment and reject_payment.

Safety Contract

No tool can directly broadcast a transaction.
Every proposal is evaluated by the wallet's attached policy.
approve_proposal is never exposed to OpenAI or LangChain agents.
All tools return structured JSON.