Metadata-Version: 2.2
Name: cobo-agentic-wallet
Version: 0.1.34
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-python-sdk
Project-URL: Documentation, https://github.com/CoboGlobal/cobo-agentic-wallet-python-sdk#readme
Project-URL: Repository, https://github.com/CoboGlobal/cobo-agentic-wallet-python-sdk
Project-URL: Issues, https://github.com/CoboGlobal/cobo-agentic-wallet-python-sdk/issues
Project-URL: Changelog, https://github.com/CoboGlobal/cobo-agentic-wallet-python-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.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.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 Agentic Wallet

Python and TypeScript SDK surfaces, MCP server, and agent-framework integrations for Cobo Agentic Wallet.

This repo is for developers building AI agents, bots, and automations that:

- move funds
- make payments
- sign messages
- interact with smart contracts
- need scoped authorization instead of raw wallet custody

Instead of giving an agent a private key, Cobo Agentic Wallet gives it a controlled runtime surface:

- pair once with the wallet owner
- submit a pact for a task
- operate within owner-approved boundaries
- receive structured denial feedback when a request is blocked
- keep signing and key management outside the agent runtime

Most developers should start with `Agent Mode`.

`Core Mode` and `Owner Mode` exist, but they are advanced options available upon request.

[![PyPI version](https://img.shields.io/pypi/v/cobo-agentic-wallet)](https://pypi.org/project/cobo-agentic-wallet/)
[![Python versions](https://img.shields.io/pypi/pyversions/cobo-agentic-wallet)](https://pypi.org/project/cobo-agentic-wallet/)
[![License](https://img.shields.io/github/license/CoboGlobal/cobo-agentic-wallet-python-sdk)](https://github.com/CoboGlobal/cobo-agentic-wallet-python-sdk/blob/main/LICENSE)

## Related CAW repositories

These repos are expected CAW open-source entry points. Placeholder links are included here until they are published:

- [CAW Python SDK](https://github.com/CoboGlobal/cobo-agentic-wallet-python-sdk)
- [CAW TypeScript SDK](https://github.com/CoboGlobal/cobo-agentic-wallet-typescript-sdk)
- [CAW Golang SDK](https://github.com/CoboGlobal/cobo-agentic-wallet-go-sdk)
- [CAW CLI](https://github.com/CoboGlobal/cobo-agentic-wallet-cli)

## What this repo includes

- **Python SDK** (`WalletAPIClient`) — async client for wallet, pact, and transaction operations
- **TypeScript SDK** (`@cobo/agentic-wallet`) — TypeScript client for wallet, pact, and transaction operations
- **MCP server** — expose wallet tools to any MCP-compatible host
- **Framework integrations** — Python: LangChain, OpenAI Agents SDK, Agno, CrewAI; TypeScript: LangChain, OpenAI Agents SDK, Vercel AI SDK, Mastra; narrow the tool surface with `include_tools` / `exclude_tools`
- **Examples** — runnable SDK and framework integration examples under [`examples/`](examples/)
- **Agent skills** — ready-to-use skill definitions under [`skills/`](skills/)

## Onboarding

### 1. Install the `caw` CLI

```bash
curl -fsSL https://raw.githubusercontent.com/CoboGlobal/cobo-agentic-wallet/master/install.sh | bash
```

Then add `caw` to your PATH:

```bash
export PATH="$HOME/.cobo-agentic-wallet/bin:$PATH"
```

### 2. Onboard and pair with the wallet owner

Run the interactive onboarding wizard. You will need an invitation code from the wallet owner.

```bash
caw onboard --invitation-code <invitation-code>
```

The wizard runs through several phases until `wallet_status` becomes `active`.

Once the wallet is active, generate a 8-digit  pairing token for the wallet owner:

```bash
caw wallet pair
```

Wallet owner need download the `Cobo Agentic Wallet` App, then enter the token to complete ownership pairing. Check pairing status with:

```bash
caw wallet pair-status
```

### 3. Get credentials

```bash
caw wallet current
```

Export the values as environment variables:

```bash
export AGENT_WALLET_API_URL=<api_url>
export AGENT_WALLET_API_KEY=<api_key>
export AGENT_WALLET_WALLET_ID=<wallet_uuid>
```

### 4. Install the SDK

**Python:**

```bash
pip install cobo-agentic-wallet
```

**TypeScript:**

```bash
npm install @cobo/agentic-wallet
```

### 5. Verify access — list wallet addresses

**Python:**

```python
import asyncio
import os
from cobo_agentic_wallet.client import WalletAPIClient

async def main() -> None:
    async with WalletAPIClient(
        base_url=os.environ["AGENT_WALLET_API_URL"],
        api_key=os.environ["AGENT_WALLET_API_KEY"],
    ) as client:
        wallet_id = os.environ["AGENT_WALLET_WALLET_ID"]

        wallets = await client.list_wallets()
        print("wallets:", wallets)

        addresses = await client.list_wallet_addresses(wallet_id)
        for addr in addresses:
            print(addr["chain_type"], addr["address"])

asyncio.run(main())
```

**TypeScript:**

```typescript
import { Configuration, WalletsApi } from '@cobo/agentic-wallet';

const config = new Configuration({
  apiKey: process.env.AGENT_WALLET_API_KEY!,
  basePath: process.env.AGENT_WALLET_API_URL!,
});

const walletsApi = new WalletsApi(config);

async function main(): Promise<void> {
  const walletId = process.env.AGENT_WALLET_WALLET_ID!;

  const wallets = await walletsApi.listWallets();
  console.log('wallets:', wallets.data.result);

  const addresses = await walletsApi.listWalletAddresses(walletId);
  for (const addr of addresses.data.result) {
    console.log(addr.chain_type, addr.address);
  }
}

main().catch(console.error);
```

### 6. Submit a pact and execute

See the [developer quickstart](https://www.cobo.com/products/agentic-wallet/manual/developer/quickstart-overview) for the full pact → approval → execution → audit flow.

### 7. Add MCP or an agent framework

Use a framework only after the direct SDK flow works.

## MCP server

Run the stdio MCP server:

```bash
AGENT_WALLET_API_URL=https://api.agenticwallet.cobo.com \
AGENT_WALLET_API_KEY=your-api-key \
python -m cobo_agentic_wallet.mcp
```

Keep the MCP surface narrow when possible:

```bash
AGENT_WALLET_INCLUDE_TOOLS=submit_pact,get_pact,contract_call,get_transaction_record_by_request_id,get_audit_logs \
python -m cobo_agentic_wallet.mcp
```

Example Claude Desktop config:

```json
{
  "mcpServers": {
    "cobo-agentic-wallet": {
      "command": "python",
      "args": ["-m", "cobo_agentic_wallet.mcp"],
      "env": {
        "AGENT_WALLET_API_URL": "https://api.agenticwallet.cobo.com",
        "AGENT_WALLET_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Framework integrations

Use a framework only after the first direct SDK flow works.

### Python

| Framework | Install | Entry point |
|---|---|---|
| LangChain | `pip install "cobo-agentic-wallet[langchain]"` | `from cobo_agentic_wallet.integrations.langchain import CoboAgentWalletToolkit` |
| OpenAI Agents SDK | `pip install "cobo-agentic-wallet[openai]"` | `from cobo_agentic_wallet.integrations.openai import create_cobo_agent` |
| Agno | `pip install "cobo-agentic-wallet[agno]"` | `from cobo_agentic_wallet.integrations.agno import CoboAgentWalletTools` |
| CrewAI | `pip install "cobo-agentic-wallet[crewai]"` | `from cobo_agentic_wallet.integrations.crewai import CoboAgentWalletCrewAIToolkit` |

### TypeScript

For the TypeScript SDK, see [CAW TypeScript SDK](https://github.com/CoboGlobal/cobo-agentic-wallet-typescript-sdk). The normal pattern is to wrap `@cobo/agentic-wallet` in framework-native tools.

Recommended TypeScript framework paths:

- LangChain
- OpenAI Agents SDK
- Vercel AI SDK
- Mastra

All framework integrations support narrowing the CAW tool surface with `include_tools` and `exclude_tools`.

Recommended presets:

- **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`

## Examples

Runnable examples live under [`examples/`](examples/):

**Python:**

- [Direct SDK](examples/python/direct_sdk.py)
- [LangChain](examples/python/langchain_agent.py)
- [OpenAI Agents SDK](examples/python/openai_agent.py)
- [Agno](examples/python/agno_agent.py)
- [CrewAI](examples/python/crewai_agent.py)

**TypeScript:**

- [Direct SDK](examples/typescript/direct_sdk.ts)
- [LangChain](examples/typescript/langchain_agent.ts)
- [OpenAI Agents SDK](examples/typescript/openai_agent.ts)
- [Vercel AI SDK](examples/typescript/vercel_ai_sdk.ts)
- [Mastra](examples/typescript/mastra_agent.ts)

## Skills

Agent skills live under [`skills/`](skills/). These are skill definitions that enable AI agents to operate Cobo Agentic Wallets — covering onboarding, token transfers, DeFi execution, and more.

Install the skill:

```bash
npx skills add CoboGlobal/cobo-agentic-wallet --skill cobo-agentic-wallet --yes --global
```

## Additional references

- release history: [CHANGELOG.md](CHANGELOG.md)
- license: [LICENSE](LICENSE)
