| 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
echo '{"action": "health"}' | python3 ~/.hermes/skills/hermes-trading-agent/hermes_trading.py
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:
- PnL from strategy_learner
- Research highlights from trading_research
- Trader mentality assessment
- Market narrative for the day
- 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)
Risk Rules (Non-Negotiable)
- Max 2% portfolio per trade — hard cap, no exceptions
- Max 10% total exposure across all open positions
- Hard stop-loss at -5% — auto-close, no overrides
- Never martingale — increase size only after proven edge
- Never trade with borrowed funds — only collateral on hand
- Sandbox every strategy first — minimum 10 logged trades before live tuning
- Log everything — especially losses; no unlogged trades
- Weekly review via
strategy_stats + evolve + trader_mentality
- No live trading until sandbox shows consistent edge (≥5 trades with positive Sharpe)
- Governance flip —
"mode": "live" in trading.json requires ≥10 sandbox trades logged AND agent approval
Setup Checklist
- SDK already installed in Hermes venv:
/Users/agentos/.hermes/hermes-agent/venv/bin/python3.11
- Private key already stored in dedicated keychain
- 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
- Fund wallet: Base ETH for gas + USDC collateral
- Test in sandbox first: 10+ trades, log every one
- Review
strategy_stats and evolve output
- Get agent approval to flip
"mode": "live" in trading.json
- 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 accessreferences/trading-delegation-protocol.md — Which research tasks route to which profilesreferences/trading-research-module.md — Market intelligence module documentationreferences/setup-python-env.md — SDK installation and Python envreferences/sdk-api-mismatches.md — 7 SDK bugs found and fixed (May 19 rewrite)references/keychain-dedicated-pattern.md — Dedicated keychain file approach and Python accessreferences/tools-schema.md — Full tool JSON schemareferences/sandbox-benchmark.md — Sandbox testing methodology
Tags for Hermes Discovery
#trading #avantis #base #defi #strategy #sandbox #keychain #mcp #prediction-markets
