demo-agentic-hedgefund-hedera-cli

A reference demo that extends hiero-ledger/hiero-cli with two SaucerSwap DEX plugins, used to drive an Agentic Hedge Fund — a set of composable Claude Code agents that use the CLI as their execution layer for DeFi operations on Hedera.

Plugins

saucerswap-v1 — SaucerSwap V1 DEX Plugin

Wraps the SaucerSwap V1 (Uniswap V2-style constant-product AMM) contracts and REST API. Tokens are resolved as Hedera entity references (ID, alias, EVM address, or HBAR). Amounts accept display units or raw base units with a t suffix.

Command	Summary
deposit	Add liquidity to an existing V1 pool
withdraw	Remove liquidity from a V1 pool
swap	Swap exact input for at least a minimum output
buy	Swap up to a maximum input for an exact output
list	List V1 pools from the SaucerSwap REST API
view	Show reserves and metadata for a specific V1 pool

Read-only commands (list, view) require a --api-key (SaucerSwap x-api-key header).

See ADR-001 for full design decisions and contract addresses.

---

saucerswap-v2 — SaucerSwap V2 Concentrated Liquidity Plugin

Wraps the SaucerSwap V2 (Uniswap V3-style) contracts. Positions are NFT-based; swaps are routed through fee-tiered pools. Parameters are ABI-encoded and submitted via multicall.

Command	Summary
swap	Swap exact input for a minimum output on a V2 pool
buy	Swap up to a maximum input for an exact output (V2)
mint-position	Create a new concentrated liquidity position (NFT)
increase-liquidity	Add liquidity to an existing V2 position
decrease-liquidity	Remove liquidity from a V2 position
collect-fees	Collect accrued swap fees from a V2 position
list-pools	List V2 pools from the SaucerSwap REST API
view-pool	Resolve and enrich a specific V2 pool
list-positions	List V2 NFT positions held by an account

Fee tiers: 500 (0.05%), 1500 (0.15%), 3000 (0.30%), 10000 (1.00%).

Read-only commands (list-pools, view-pool, list-positions) require a --api-key.

See ADR-002 for full design decisions and contract addresses.

---

dex-market — DEX Market Data Plugin

Read-only market data for Hedera tokens. Pulls prices, pools, pairs, liquidity, and quotes from the DexScreener public API and resolves Hedera token IDs through the Hedera Mirror Node. No API key required.

Command	Summary
price	Fetch current price data for one or more tokens (up to 30)
pools	List liquidity pools for a token, sorted by liquidity
pair	Fetch full details for a specific pair contract address
search	Search DexScreener pairs on Hedera by symbol, name, or address
liquidity	Aggregate liquidity across all pools and check a USD threshold
quote	Estimate price impact (slippage) for a USD position size

Example usage:

hcli dex-market price --token 0.0.731861 --token 0.0.456858
hcli dex-market pools --token 0.0.731861 --limit 10
hcli dex-market search --query SAUCE --limit 10
hcli dex-market pair --pair 0x4A46705176faC8Fd5C8061F94A2C44416e7B20e6
hcli dex-market liquidity --token 0.0.731861 --min-usd 10000
hcli dex-market quote --token 0.0.731861 --size 1000

quote output is a constant-product approximation — not a router-grade executable quote.

---

SaucerSwap API Key

Several commands query the SaucerSwap REST API and require an --api-key argument, which is forwarded as the x-api-key request header.

To obtain a key, follow the authentication guide in the SaucerSwap developer documentation: https://docs.saucerswap.finance/v/developer/rest-api/authentication

Once you have a key, pass it to any read-only command:

hcli saucerswap-v1 list --api-key <your-api-key>
hcli saucerswap-v2 list-pools --api-key <your-api-key>

---

Building

Requirements: Node.js ≥ 18

npm install
npm run build

The build runs Prettier, compiles TypeScript, and resolves path aliases. Compiled plugins are emitted to dist/plugins/.

Other useful scripts:

npm run lint          # ESLint check
npm run lint:fix      # ESLint auto-fix
npm run format        # Prettier write
npm run format:check  # Prettier check

---

Adding the Plugins to hiero-cli

After building, register each plugin with the plugin-management add command of your local hcli installation:

# SaucerSwap V1
hcli plugin-management add -p dist/plugins/saucerswap-v1/

# SaucerSwap V2
hcli plugin-management add -p dist/plugins/saucerswap-v2/

# DEX Market
hcli plugin-management add -p dist/plugins/dex-market/

Once registered, the commands are available as subcommands of the plugin name:

hcli saucerswap-v1 list --api-key <key>
hcli saucerswap-v1 swap --from HBAR --to 0.0.12345 --amount 10

hcli saucerswap-v2 list-pools --api-key <key>
hcli saucerswap-v2 swap --from HBAR --to 0.0.12345 --amount 5 --fee-tier 3000

hcli dex-market price --token 0.0.731861
hcli dex-market pools --token 0.0.731861 --limit 10

---

Claude Code Skills (Agentic Hedge Fund)

The skills/ directory contains Claude Code agent skills that drive the Agentic Hedge Fund scenarios. To activate them, copy the skill directories into your Claude Code skills folder.

Scope: use the global path (~/.claude/skills/ / %USERPROFILE%\.claude\skills\) to make skills available in every project, or the project-local path (.claude/skills/) to keep them scoped to this repo only. After copying, restart Claude Code so the new skills are picked up.

Linux

# Global
cp -r skills/* ~/.claude/skills/

# Project-local
cp -r skills/* .claude/skills/

macOS

# Global
cp -r skills/* ~/.claude/skills/

# Project-local
cp -r skills/* .claude/skills/

Windows (PowerShell)

# Global
Copy-Item -Recurse skills\* "$env:USERPROFILE\.claude\skills\"

# Project-local
Copy-Item -Recurse skills\* .claude\skills\

---

Available Skills

Skill	Description
agentic-hedge-fund-saucerswap	Flow 1 — observe a V1/V2 pool, compute an implied price, and execute a risk-checked swap or buy
agentic-hedge-fund-rebalance	Flow 2 — atomic portfolio rebalance (transfer → swap → deposit) via a HIP-551 batch
agentic-hedge-fund-yield-entry	Flow 4 entry — discover the deepest liquidity pool for a pair and enter a yield farming position
agentic-hedge-fund-yield-monitor	Flow 4 monitor — watch an open LP position for impermanent loss and exit automatically when the threshold is exceeded

Invoke skills inside Claude Code with /agentic-hedge-fund-saucerswap, /agentic-hedge-fund-rebalance, etc.

---

Repository Layout

src/
├── plugins/
│   ├── saucerswap-v1/   # V1 plugin source
│   ├── saucerswap-v2/   # V2 plugin source
│   └── dex-market/      # DEX market data plugin source (DexScreener)
└── shared/              # Shared services, schemas, and utilities
docs/
├── adr/                 # Architecture Decision Records
└── PRD-agentic-hedge-fund.md