Skip to main content

​
Overview

AgentWalletToolkit provides the canonical CAW runtime tool surface that framework-specific integrations (LangChain, OpenAI, MCP) consume and adapt to their runtimes.

​
Constructor

from cobo_agentic_wallet.client import WalletAPIClient
from cobo_agentic_wallet.toolkit import AgentWalletToolkit

client = WalletAPIClient(base_url="http://localhost:8000", api_key="...")
toolkit = AgentWalletToolkit(client=client)
For production docs and examples, prefer https://api.agenticwallet.cobo.com as the API base URL. You can also restrict the canonical surface up front: 
toolkit = AgentWalletToolkit(
    client=client,
    include_tools=["submit_pact", "get_pact", "contract_call", "get_transaction_record_by_request_id"],
)
include_tools keeps only the named tools, in the same order you provide. exclude_tools removes tools from the default surface. This selection propagates cleanly to LangChain, OpenAI Agents SDK, and MCP-backed custom usage when those adapters are built from the toolkit. Most agentic runtimes should start with a smaller role-based subset rather than the full 20-tool surface.
  • Pact Drafting — submit_pact, get_pact, list_pacts
  • Execution — transfer_tokens, contract_call, estimate_transfer_fee, estimate_contract_call_fee, get_transaction_record_by_request_id
  • Observer — list_wallets, get_wallet, get_balance, list_transaction_records, get_audit_logs
These presets map well to common runtime responsibilities:
  • draft and monitor scoped authorization
  • execute approved blockchain actions or payments
  • inspect balances, records, and audit history

​
get_tools()

Returns ToolDefinition objects for the full 20-tool runtime surface. The tables below list only the required parameters for each tool. Most tools accept additional optional parameters — for the full parameter surface of each tool, see the Python SDK reference.

​
Wallet context

ToolRequired ParametersPurpose
list_wallets—Discover wallets accessible to the caller.
get_walletwallet_uuidInspect wallet metadata and status.
list_wallet_addresseswallet_uuidList on-chain addresses for a wallet.
get_balancewallet_uuidGet token balances, optionally filtered by chain or token.

​
Scoped authority

ToolRequired ParametersPurpose
submit_pactwallet_id, intent, specSubmit a pact for owner approval.
get_pactpact_idFetch the latest pact status and details.
list_pacts—List pacts visible to the caller.
create_delegationoperator_id, wallet_id, permissionsCreate a delegation directly when needed.

​
Onchain and payment actions

ToolRequired ParametersPurpose
transfer_tokenswallet_uuid, chain_id, dst_addr, token_id, amountSubmit a transfer with policy enforcement.
contract_callwallet_uuid, chain_idSubmit a smart-contract call with policy enforcement.
message_signwallet_uuid, chain_idSign a message or typed data without broadcasting.
paymentwallet_uuid, protocolSubmit an x402 or MPP payment request.
estimate_transfer_feewallet_uuid, dst_addr, amountPreview a transfer fee before submission.
estimate_contract_call_feewallet_uuid, chain_idPreview a contract-call fee before submission.

​
Tracking and audit

ToolRequired ParametersPurpose
list_transactionswallet_uuidList live transactions associated with a wallet.
list_transaction_recordswallet_uuidList persisted transaction records across operation types.
get_transaction_recordwallet_uuid, record_uuidFetch a transaction record by record UUID.
get_transaction_record_by_request_idwallet_uuid, request_idLook up a record by idempotency request ID.
list_recent_addresseswallet_uuidRetrieve recently used destination addresses.
get_audit_logs—Query actions, denials, approvals, and other audit events.
list_transactions is retained for compatibility with earlier integrations. For durable runtime tracking, prefer list_transaction_records and get_transaction_record_by_request_id.

​
ToolDefinition

@dataclass(frozen=True)
class ToolDefinition:
    name: str                    # Unique tool ID
    description: str             # Human/LLM description
    parameters: dict[str, Any]   # JSON Schema
    handler: ToolHandler         # async callable
Each ToolDefinition includes a JSON Schema for parameters that framework adapters use to generate type-safe input models (e.g., Pydantic schemas for LangChain, function schemas for OpenAI).

​
Handler Pattern

Tool handlers are async callables that invoke WalletAPIClient methods: 
tools = toolkit.get_tools()
transfer_tool = next(t for t in tools if t.name == "transfer_tokens")

# Call the handler directly
result = await transfer_tool.handler(
    wallet_uuid="...",
    chain_id="ETH",
    dst_addr="0x...",
    token_id="USDT",
    amount="10",
)

​
Denial Formatting

The toolkit provides a static method for formatting policy denials into LLM-readable guidance: 
from cobo_agentic_wallet.toolkit import AgentWalletToolkit

formatted = AgentWalletToolkit._format_denial(denial)
# Output:
# Policy Denied [TRANSFER_LIMIT_EXCEEDED]: max_per_tx
#   limit_value: 100
#   requested: 1000
# Suggestion: Retry with amount <= 100.
Framework integrations use this formatting to return denials as readable tool output rather than raising exceptions, which lets the agent adapt and retry.

Source Code

src/cobo_agentic_wallet/toolkit.py