Metadata-Version: 2.2
Name: cobo-agentic-wallet
Version: 0.1.13
Summary: Python SDK for Cobo Agent Wallet - The Programmable Bank for Autonomous Agents
Author-email: Cobo <dev@cobo.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/CoboGlobal/cobo-agentic-wallet-sdk
Project-URL: Documentation, https://github.com/CoboGlobal/cobo-agentic-wallet-sdk#readme
Project-URL: Repository, https://github.com/CoboGlobal/cobo-agentic-wallet-sdk
Project-URL: Issues, https://github.com/CoboGlobal/cobo-agentic-wallet-sdk/issues
Project-URL: Changelog, https://github.com/CoboGlobal/cobo-agentic-wallet-sdk/blob/main/CHANGELOG.md
Keywords: agent,wallet,crypto,cobo,mcp,llm,ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: typer>=0.12.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: urllib3>=2.6.3
Requires-Dist: typing-extensions>=4.7.1
Requires-Dist: pynacl>=1.6.0
Provides-Extra: mcp
Requires-Dist: fastmcp>=3.0.0; extra == "mcp"
Provides-Extra: langchain
Requires-Dist: langchain>=1.0.0; extra == "langchain"
Provides-Extra: openai
Requires-Dist: openai-agents>=0.10.4; extra == "openai"
Provides-Extra: agno
Requires-Dist: agno>=2.4.8; extra == "agno"
Provides-Extra: all
Requires-Dist: fastmcp>=3.0.0; extra == "all"
Requires-Dist: langchain>=1.0.0; extra == "all"
Requires-Dist: openai-agents>=0.10.4; extra == "all"
Requires-Dist: agno>=2.4.8; extra == "all"
Provides-Extra: crewai
Requires-Dist: crewai>=1.9.3; extra == "crewai"
Provides-Extra: agent-frameworks
Requires-Dist: langchain>=1.0.0; extra == "agent-frameworks"
Requires-Dist: openai-agents>=0.10.4; extra == "agent-frameworks"
Requires-Dist: agno>=2.4.8; extra == "agent-frameworks"
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Requires-Dist: respx>=0.21.0; extra == "dev"
Requires-Dist: aioresponses>=0.7.4; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: fastmcp>=3.0.0; extra == "dev"
Requires-Dist: langchain>=1.0.0; extra == "dev"
Requires-Dist: openai-agents>=0.10.4; extra == "dev"
Requires-Dist: agno>=2.4.8; extra == "dev"

# Cobo Agent Wallet SDK

> Don't give your agent a wallet. Give it a Budget and a Rulebook.

[![PyPI version](https://img.shields.io/pypi/v/cobo-agent-wallet)](https://pypi.org/project/cobo-agent-wallet/)
[![Python versions](https://img.shields.io/pypi/pyversions/cobo-agent-wallet)](https://pypi.org/project/cobo-agent-wallet/)
[![License](https://img.shields.io/github/license/CoboGlobal/cobo-agent-wallet-sdk)](https://github.com/CoboGlobal/cobo-agent-wallet-sdk/blob/main/LICENSE)
[![CI](https://github.com/CoboGlobal/cobo-agent-wallet-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/CoboGlobal/cobo-agent-wallet-sdk/actions/workflows/ci.yml)

The Cobo Agent Wallet SDK lets AI agents manage crypto wallets with built-in policy guardrails. Instead of giving your agent unrestricted access to a wallet, you define budgets, spending limits, and rules — the policy engine enforces them automatically.

## Features

- **Policy Engine** — Per-transaction limits, daily/monthly budgets, token allowlists. Denials include structured reasons and suggestions so agents can self-correct.
- **Delegation Model** — Owners define what agents can do. Agents operate within those boundaries without needing owner keys.
- **Agent-Ready Errors** — Every policy denial returns `suggestion` and `details` fields designed for LLM consumption, enabling autonomous retry and self-correction.
- **Framework Integrations** — Drop-in toolkits for LangChain, OpenAI Agents SDK, Agno, CrewAI, and MCP.

## Quick Install

```bash
pip install cobo-agent-wallet
```

## Quickstart

```python
from cobo_agentic_wallet import WalletAPIClient

async with WalletAPIClient(base_url="http://localhost:8000", api_key="your-key") as client:
    wallets = await client.list_wallets()
    print(wallets)
```

> **Note:** Provisioning principals and API keys requires a trusted service credential
> (`X-Assistant-Service-Key` header) in production. In development, the backend's docker-compose
> stack enables `ALLOW_PUBLIC_BOOTSTRAP=true`, which allows unauthenticated principal/key
> creation without the service credential (localhost only, dev ENV gate enforced).

## Supported API Methods

The SDK provides **34+ API methods** covering wallet management, transactions, policies, delegations, and more:

**Core Methods** (7 canonical tools via toolkit):
- `list_wallets()`, `get_wallet()`, `get_balance()` — Wallet queries
- `transfer()`, `estimate_fee()` — Token transfers
- `list_transactions()`, `get_audit_logs()` — Audit & history
- `create_delegation()`, `list_delegations()` — Operator delegation
- `dry_run_policy()` — Policy dry-run

**Advanced Methods** (direct client access):
- **Smart Contracts**: `contract_call()`, `estimate_contract_call_fee()`, `get_transaction()`
- **Policy Management**: `list_policies()`, `get_policy()`, `update_policy()`, `delete_policy()`, `dry_run_policy()`
- **More**: `freeze()`, `unfreeze()`, `revoke_delegation()`, `create_principal()`, `create_api_key()`, `create_address()`, `create_policy()`

See [API Reference](docs/api-reference.md) for complete documentation.

## Framework Integrations

| Framework | Install | Import |
|-----------|---------|--------|
| LangChain | `pip install cobo-agent-wallet[langchain]` | `from cobo_agentic_wallet.integrations.langchain import CoboAgentWalletToolkit` |
| OpenAI Agents | `pip install cobo-agent-wallet[openai]` | `from cobo_agentic_wallet.integrations.openai import get_cobo_tools` |
| Agno | `pip install cobo-agent-wallet[agno]` | `from cobo_agentic_wallet.integrations.agno import CoboAgentWalletTools` |
| CrewAI | `pip install cobo-agent-wallet[crewai]` | `from cobo_agentic_wallet.integrations.crewai import CoboAgentWalletCrewAIToolkit` |
| MCP | `pip install cobo-agent-wallet[mcp]` | `python -m cobo_agentic_wallet.mcp` |

## MCP Server

Run the MCP server for use with Claude Desktop or other MCP clients:

```bash
AGENT_WALLET_API_URL=http://localhost:8000 \
AGENT_WALLET_API_KEY=your-key \
python -m cobo_agentic_wallet.mcp
```

Add to your MCP client config:

```json
{
  "mcpServers": {
    "cobo-agent-wallet": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/sdk", "python", "-m", "cobo_agentic_wallet.mcp"],
      "env": {
        "AGENT_WALLET_API_URL": "http://localhost:8000",
        "AGENT_WALLET_API_KEY": "your-api-key"
      }
    }
  }
}
```

## CLI

```bash
# Run the quickstart demo
AGENT_WALLET_API_URL=http://localhost:8000 caw demo

# List wallets
AGENT_WALLET_API_URL=http://localhost:8000 AGENT_WALLET_API_KEY=your-key caw list-wallets
```

## Why AgentWallet?

Giving an AI agent direct access to a crypto wallet is like giving an intern the company credit card with no spending limit. AgentWallet solves this with:

1. **Delegations** — Define per-transaction, daily, and monthly limits. The agent operates within these boundaries.
2. **Policy Engine** — Every transfer is checked against the delegation rules before execution. No exceptions.
3. **Structured Denials** — When a transfer is denied, the agent receives a machine-readable explanation with a `suggestion` field it can use to retry with adjusted parameters.
4. **Audit Trail** — Every transfer attempt (allowed and denied) is logged with full context.

## Agent Recipes

Ready-to-use examples for common use cases:

- Discord Tip Bot
- DCA Trader
- Treasury Manager
- NFT Minter
- Cross-Chain Arbitrageur

See [`examples/recipes/`](examples/recipes/) for full implementations.

## Development

```bash
git clone https://github.com/CoboGlobal/cobo-agent-wallet-sdk.git
cd cobo-agent-wallet-sdk
uv sync --extra dev
make lint
make test
```

## Documentation

- [API Reference](docs/api-reference.md)
- [Framework Guides](docs/guides/)
- [Agent Recipes](docs/recipes/)
- [Contributing](.github/CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.
