ergo-agent-sdk 0.2.0

Open-source Python SDK for AI agents to interact with the Ergo blockchain

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.

---

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

pip install ergo-agent

Read-only (no wallet needed)

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)

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

# 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:

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:

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