Metadata-Version: 2.4
Name: ergo-agent-sdk
Version: 0.2.0
Summary: Open-source Python SDK for AI agents to interact with the Ergo blockchain
Project-URL: Homepage, https://github.com/ergoplatform/ergo-agent-sdk
Project-URL: Documentation, https://ergo-agent.readthedocs.io
Project-URL: Repository, https://github.com/ergoplatform/ergo-agent-sdk
Project-URL: Issues, https://github.com/ergoplatform/ergo-agent-sdk/issues
License: MIT
Keywords: agent,ai,blockchain,defi,ergo,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.8.0
Provides-Extra: all
Requires-Dist: anthropic>=0.30.0; extra == 'all'
Requires-Dist: langchain-core>=0.2.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: ipykernel>=6.0.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25.0; extra == 'docs'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# ergo-agent 🤖⛓️

> **Open-source Python SDK for AI agents on the Ergo blockchain.**

Give any LLM agent (Claude, GPT-4, LangChain, CrewAI...) the ability to read wallet balances, fetch live prices, swap tokens on Spectrum DEX — all autonomously, with built-in safety guardrails.

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

## Why?

Existing Ergo SDKs (ergpy, fleet-sdk, AppKit) are built for **human developers**. This SDK is built for **AI agents** — it speaks the language of function calling, returns structured JSON, and has a safety layer so the agent can't accidentally drain a wallet.

---

## Quickstart

```bash
pip install ergo-agent
```

### Read-only (no wallet needed)

```python
from ergo_agent import ErgoNode, Wallet
from ergo_agent.tools import ErgoToolkit, SafetyConfig

node = ErgoNode()
wallet = Wallet.read_only("9f...")  # any address to monitor
toolkit = ErgoToolkit(node=node, wallet=wallet)

# Check address balance
result = toolkit.get_wallet_balance()

# Get live ERG/USD price from Oracle Pool v2
price = toolkit.get_erg_price()

# Get a swap quote from Spectrum DEX
quote = toolkit.get_swap_quote(token_in="ERG", token_out="SigUSD", amount_erg=1.0)
```

### With a wallet (transactions enabled)

```python
from ergo_agent import ErgoNode, Wallet
from ergo_agent.tools import ErgoToolkit, SafetyConfig

node = ErgoNode(node_url="http://your-node:9053", api_key="your-key")
wallet = Wallet.from_node_wallet("9f...")

toolkit = ErgoToolkit(
    node=node,
    wallet=wallet,
    safety=SafetyConfig(
        max_erg_per_tx=5.0,
        max_erg_per_day=50.0,
        allowed_contracts=["spectrum"],
        rate_limit_per_hour=20,
    )
)

# Send ERG
toolkit.send_erg(to="9f...", amount_erg=1.5)

# Swap ERG for a token on Spectrum DEX
toolkit.swap_erg_for_token(token_out="SigUSD", amount_erg=1.0)
```

### Use with LLM frameworks

```python
# OpenAI function calling
tools = toolkit.to_openai_tools()

# Anthropic tool use
tools = toolkit.to_anthropic_tools()

# LangChain
lc_tools = toolkit.to_langchain_tools()
```

---

## Available Tools

| Tool | Description | Requires Wallet |
|---|---|---|
| `get_wallet_balance` | ERG + token balances | No |
| `get_erg_price` | Live ERG/USD from Oracle Pool v2 | No |
| `get_swap_quote` | Spectrum DEX swap quote | No |
| `get_mempool_status` | Pending transactions | No |
| `get_safety_status` | Current spending limits & usage | No |
| `send_erg` | Send ERG to an address | Yes |
| `swap_erg_for_token` | Execute a swap on Spectrum DEX | Yes |

---

## Architecture

```
ergo_agent/
├── core/        # ErgoNode client, Wallet, TransactionBuilder, Address utilities
├── defi/        # Oracle Pool v2, Spectrum DEX adapters
└── tools/       # LLM tool schemas (OpenAI / Anthropic / LangChain) + safety layer
```

---

## Safety Layer

Every state-changing action passes through `SafetyConfig` before execution:

```python
SafetyConfig(
    max_erg_per_tx=10.0,                  # hard cap per transaction
    max_erg_per_day=50.0,                 # daily rolling limit
    allowed_contracts=["spectrum"],        # contract whitelist
    rate_limit_per_hour=20,               # max 20 actions/hour
    dry_run=False,                        # set True for dry-run mode
)
```

---

## Network

By default the SDK connects to the **Ergo public API** (`https://api.ergoplatform.com`). For production use or transaction signing, point it at your own node:

```python
node = ErgoNode(node_url="http://your-node:9053", api_key="your-key")
```

---

## Contributing

This is an open-source project for the Ergo ecosystem. PRs welcome.

**Roadmap:**
- v0.1.0 — Core + Oracle + Spectrum + Tool schemas + Safety layer *(current)*
- v0.2.0 — SigmaUSD + Rosen Bridge adapters
- v0.3.0 — Treasury contract (ErgoScript on-chain spending limits)

---

## License

MIT
