trading-pulse

name	trading-pulse
title	Trading Pulse — Avantis Perps + Polymarket Intelligence
description	Self-improving trading agent for Avantis perps on Base and prediction markets. Includes dedicated keychain wallet, sandbox-first validation, strategy evolution, market intelligence (sentiment, geopolitics, narratives), trader mentality scoring, daily PnL summaries, MCP server for external tooling, and wiki-llm knowledge base.
type	workflow
version	2.0.0
trigger	When user asks to trade, find flips, check positions, test strategies, grow wallet, log research, get a daily summary, or assess trader mentality
status	active
created	"2026-05-18T00:00:00.000Z"
updated	"2026-05-19T00:00:00.000Z"
category	finance
license	MIT
tested	schema-only
tested_note	Schema validated; paper-trading references are documented but not executed by this repo.
tags	["trading","avantis","polymarket","defi","prediction-markets","risk-management","strategy-learning","sandbox-testing","market-intelligence","trader-mentality","mcp","keychain","base-chain"]
related_skills	["wiki-llm","kanban-orchestrator","delegation-toolchain","polymarket","trading-pulse"]
tools	["terminal","web","browser"]

Trading Pulse — Avantis + Polymarket Intelligence Pipeline

v2.0 — Self-improving, research-driven trading agent with dedicated keychain, sandbox validation, strategy evolution, market intelligence, and MCP integration.

Architecture

Hermes Agent (Chief Profile)
├── avantis_trader.py        — Live/sandbox trade execution via Avantis SDK
├── hermes_trading.py        — Unified launcher: 25 JSON-RPC action routes
├── strategy_learner.py      — Trade logging, rolling stats, evolution engine
├── sandbox.py               — Simulated trading ($10K virtual balance)
├── trading_research.py      — Market intelligence, sentiment, daily summaries
├── mcp_server.py            — JSON-RPC server for external tool access
└── description.js           — Self-description for Hermes skill discovery

Keychain Wallet Integration

Dedicated Keychain File (not system keychain)

Private key stored in an isolated macOS Keychain file — no GUI auth prompts, no system keychain pollution, headless CLI safe.

Property	Value
File	~/.hermes/profiles/chief/trading.keychain
Service	com.hermes.trading.wallet
Account	base-wallet-private-key
Wallet	0x1791e9C595Afb2Dbb18Ec1bB0F384E4e75Ef4b47
Network	Base (mainnet, chain ID 8453)
RPC	https://mainnet.base.org
L1 RPC	https://eth.llamarpc.com

Keychain Pitfalls (Learned — May 19 update)

• Dedicated .keychain file required: Without passing the keychain file path, security CLI accesses the system keychain which triggers GUI auth prompts in headless mode.
• delete-then-add pattern: Prevents duplicate-item errors on repeated setup calls.
• 0x prefix handling: keychain_load_private_key() strips then re-adds 0x to prevent double-prefix bugs (0x0x...).
• Python path: Must use Hermes venv Python (/Users/agentos/.hermes/hermes-agent/venv/bin/python3.11). System Python (3.9) lacks the SDK.

SDK API Notes (May 19 fix)

• LocalSigner requires async_web3 param: Don't use LocalSigner(private_key) directly — use client.set_local_signer(private_key) instead.
• load_contracts() is sync, not async: Don't await it. Call client.load_contracts() synchronously.
• has_signer() returns dict: Not a simple boolean. Don't await it.
• LocalSigner uses get_ethereum_address(): Not .address. Use signer.get_ethereum_address().
• All data methods are async: get_usdc_balance, get_balance, read_contract, write_contract, etc. must be awaited.

---

Hermes Trading Agent — All 25 Actions

Invocation

# Via unified launcher
echo '{"action": "health"}' | python3 ~/.hermes/skills/hermes-trading-agent/hermes_trading.py

# Via MCP server (running separately)
# Connect to localhost:9001 or wherever mcp_server.py is hosted

Module: avantis_trader (9 actions)

Action	Auth	Description
setup	key	Store Base private key in dedicated keychain file
disconnect	key	Remove key from keychain
status	—	Check wallet connection state
address	key	Derive wallet address from stored key
balance	key	Get ETH + USDC balance on Base
usdc_balance	key	Get USDC balance only
positions	key	List open leveraged positions
markets	—	List all available pairs with prices
price	—	Get mark price for a pair

Module: avantis_trader (4 actions)

Action	Auth	Description
funding_rate	—	Get current funding rate for a pair
trade	key	Open leveraged position (collateral, leverage, TP, SL)
close	key	Close a position by ID
settle	key	Settle a closed position

Module: sandbox (4 actions)

Action	Auth	Description
sandbox_trade	—	Simulate a trade with realistic fills
sandbox_summary	—	Get sandbox PnL summary and fitness score
sandbox_reset	—	Reset sandbox to $10K starting balance
sandbox_prices	—	Get simulated price feed with per-pair volatility

Module: strategy_learner (3 actions)

Action	Auth	Description
log_trade	—	Log a completed trade for learning (full metadata)
strategy_stats	—	Get performance stats (win rate, Sharpe, edge, drawdown)
evolve	—	Analyze ≥10 trades, detect loss patterns, suggest param adjustments

Module: trading_research (5 actions)

Action	Auth	Description
log_research	—	Log structured market intelligence (query, tags, source, sentiment)
research_context	—	Query accumulated intelligence for any trading pair
market_narrative	—	Aggregate themes from research + trade outcomes
daily_summary	—	PnL, research highlights, trader mentality in one report
trader_mentality	—	Score discipline, risk appetite, emotional state; flag revenge trading

Module: mcp_server (5 actions)

Action	Auth	Description
get_market_state	—	Current prices, positions, balances, open trades
get_strategy_performance	—	Rolling stats from strategy_learner
get_recent_trades	—	Last N trades with full metadata
evaluate_trade	—	Pre-trade assessment: risk, edge, sizing
log_intelligence	—	Forward market intelligence to research module

Module: system (2 actions)

Action	Auth	Description
health	—	Full system health check across all modules
help	—	List all available actions with descriptions

---

Sandbox Testing

Simulated trading environment — no real capital required, ever, until you flip the mode switch.

Features:

• $10K starting virtual balance
• Realistic fills: mean-reverting random walk with per-pair volatility
  • ETH: 3.5%, BTC: 3.0%, SOL: 5.5%, XAU: 1.2%, EUR: 0.6%
• Funding costs, 0.04% taker fee, slippage modeling
• Fitness score tracking per strategy

Data: ~/.hermes/profiles/chief/trading/sandbox_log.json

echo '{"action": "sandbox_trade",
       "trade": {"pair": "ETH/USD", "direction": "long",
                 "collateral": 500, "leverage": 10, "strategy": "sr-breakout"}}' \
  | /Users/agentos/.hermes/hermes-agent/venv/bin/python3.11 ~/.hermes/skills/hermes-trading-agent/hermes_trading.py

All commands must use the Hermes venv Python: /Users/agentos/.hermes/hermes-agent/venv/bin/python3.11 The system Python (Xcode Python 3.9) lacks the avantis-trader-sdk package.

---

Strategy Learning Engine

Records every trade → computes rolling statistics → evolves strategy parameters after ≥10 trades.

Log a Trade

{
  "action": "log_trade",
  "trade": {
    "strategy_name": "sr-breakout",
    "pair": "ETH/USD",
    "direction": "long",
    "entry_price": 3120.5,
    "exit_price": 3180.25,
    "collateral": 500,
    "leverage": 10,
    "pnl": 189.75,
    "market_conditions": "strong uptrend breakout",
    "timeframe": "4h",
    "notes": "clean entry after 2h consolidation"
  }
}

Metrics Tracked

• Win rate — per strategy and overall
• Sharpe ratio — rolling 20-trade window
• Edge — win_rate × avg_pnl
• Leverage analysis — correlation between leverage level and outcome
• Timeframe analysis — which timeframes perform best per strategy
• Drawdown tracking — max drawdown, recovery time

Evolution Engine (evolve)

• Triggers after ≥10 logged trades per strategy
• Detects if higher leverage correlates with losses
• Identifies worst-performing timeframes
• Suggests parameter adjustments (leverage, position sizing, TP/SL thresholds)
• Rule: Never auto-apply evolution suggestions — agent reviews and approves
• Pitfall (May 18): Original evolve action threw KeyError when strategy_name was missing from trade log entries. Rewrote to use .get() with safe defaults and added null-state reset for fresh trade logs. Ensure all log_trade calls include strategy_name field.

Data Location

• Strategy DB: ~/.hermes/profiles/chief/trading/strategy_db.json
• Sandbox log: ~/.hermes/profiles/chief/trading/sandbox_log.json

---

Market Intelligence & Research Module

trading_research.py — Structured Market Intelligence

• Log research with query, tags, source, sentiment, date
• Retrieve context for any trading pair
• Generate market narratives from aggregated research
• Daily PnL + mentality summaries
• Persistence in ~/.hermes/profiles/chief/trading/research/

trader_mentality Assessment

Scores based on recent trade behavior:

• Discipline — adherence to planned TP/SL, no early exits
• Risk appetite — position sizing relative to account
• Emotional state — revenge trading detection, tilt indicators
• Timing patterns — overtrading, fatigue-based errors

daily_summary Report

Combines:

1. PnL from strategy_learner
2. Research highlights from trading_research
3. Trader mentality assessment
4. Market narrative for the day
5. Evolution suggestions (if ≥10 trades logged)

Delegation Protocol

Research tasks routed to other Hermes profiles when deeper analysis needed:

Domain	Delegated To	Reason
Geopolitical analysis	intel profile	Deep research capabilities
Chart/TA analysis	forge profile	Builder-grade pattern recognition
Sentiment/meme tracking	External APIs	Polymarket, social sentiment
Strategy backtesting	forge profile	Computational heavy lifting

---

MCP Server

The trading agent exposes a JSON-RPC server for external tools to query state.

{
  "method": "get_market_state",
  "params": {}
}

Available Methods

Method	Returns
get_market_state	Current prices, positions, balances
get_strategy_performance	Rolling Sharpe, win rate, edge per strategy
get_recent_trades	Last N trades with full metadata
evaluate_trade	Pre-trade risk/edge/sizing assessment
log_intelligence	Forward market intelligence to research module

Server location: ~/.hermes/skills/hermes-trading-agent/mcp_server.py

Sandbox Results (May 19, 2026 — Post SDK-Fix Verification)

All 15 actions tested and passing after full avantis_trader.py rewrite.

Sandbox: 20 trades via pressure test, 1.8% max drawdown, SURVIVED. Strategy: 15 trades tracked, 53.3% win rate, $20.18 net PnL, 0.72 edge. Live: Wallet 0x1791e9C595Afb2Dbb18Ec1bB0F384E4e75Ef4b47 ready — unfunded (0 ETH, 0 USDC).

7 trades from initial sandbox (May 18):

#	Pair	Dir	Entry	Exit	PnL	Cum PnL
1	ETH/USD	Long	3120.50	3188.87	+$10.97	+$10.97
2	BTC/USD	Short	108250	106210.41	+$18.55	+$29.52
3	SOL/USD	Long	172.40	170.04	-$4.08	+$25.45
4	XAU/USD	Long	4503.20	4510.98	+$0.87	+$26.32
5	ETH/USD	Short	3120.50	3167.16	-$12.16	+$14.16
6	BTC/USD	Long	108250	103918.40	-$39.81	-$25.65
7	SOL/USD	Short	172.40	170.64	+$3.03	-$22.62

Stats: 4W/3L, 57.1% WR, -$22.63 net, -$1.85 edge. BTC/USD long (#6) was the worst trade. Need 3+ more trades before evolve analysis.

Find Near-Resolution Flips

url = 'https://gamma-api.polymarket.com/markets?limit=100&active=true&closed=false&order=volume24hr&ascending=false'
for m in data:
    yes_price = float(json.loads(m['outcomePrices'])[0])
    if yes_price > 0.90 and float(m.get('volume24hr', 0)) > 5000:
        edge = round(((1.0 / yes_price) - 1.0) * 100, 1)
        # High-probability outcome with decent volume = potential flip

---

Risk Rules (Non-Negotiable)

1. Max 2% portfolio per trade — hard cap, no exceptions
2. Max 10% total exposure across all open positions
3. Hard stop-loss at -5% — auto-close, no overrides
4. Never martingale — increase size only after proven edge
5. Never trade with borrowed funds — only collateral on hand
6. Sandbox every strategy first — minimum 10 logged trades before live tuning
7. Log everything — especially losses; no unlogged trades
8. Weekly review via strategy_stats + evolve + trader_mentality
9. No live trading until sandbox shows consistent edge (≥5 trades with positive Sharpe)
10. Governance flip — "mode": "live" in trading.json requires ≥10 sandbox trades logged AND agent approval

---

Setup Checklist

1. SDK already installed in Hermes venv: /Users/agentos/.hermes/hermes-agent/venv/bin/python3.11
2. Private key already stored in dedicated keychain
3. Verify: echo '{"action": "status"}' | /Users/agentos/.hermes/hermes-agent/venv/bin/python3.11 ~/.hermes/skills/hermes-trading-agent/hermes_trading.py → connected: true, rpc_ok: true, chain_id: 8453
4. Fund wallet: Base ETH for gas + USDC collateral
5. Test in sandbox first: 10+ trades, log every one
6. Review strategy_stats and evolve output
7. Get agent approval to flip "mode": "live" in trading.json
8. Start with micro-positions ($50-100 collateral)

---

Wiki-LLM Integration

Canonical knowledge base: wiki/projects/trading-agent.md

• Architecture, capabilities, risk rules, strategy evolution docs
• Schema: WIKI-LLM-SCHEMA.md defines entity types (agent, project, action, event)
• Wiki index: wiki/Index.md links to trading agent page
• Research logged here supplements strategy learner for long-term pattern recognition

---

References

• references/sdk-api-mismatches.md — 7 SDK bugs found and fixed (May 19 rewrite)
• references/keychain-dedicated-pattern.md — Dedicated keychain file approach and Python access
• references/trading-delegation-protocol.md — Which research tasks route to which profiles
• references/trading-research-module.md — Market intelligence module documentation
• references/setup-python-env.md — SDK installation and Python env
• references/sdk-api-mismatches.md — 7 SDK bugs found and fixed (May 19 rewrite)
• references/keychain-dedicated-pattern.md — Dedicated keychain file approach and Python access
• references/tools-schema.md — Full tool JSON schema
• references/sandbox-benchmark.md — Sandbox testing methodology

Tags for Hermes Discovery

#trading #avantis #base #defi #strategy #sandbox #keychain #mcp #prediction-markets