feat(agents): Derive Perp Smart-Money Flow Agent by carlito-hummingbot · Pull Request #178 · hummingbot/condor

carlito-hummingbot · 2026-07-28T15:17:31Z

Summary

Adds the Smart-Money Flow Condor agent: a directional perpetual-futures
trader that reads cross-market capital-flow + an on-chain Solana DeFi pulse
and takes bounded LONG/SHORT positions on Derive (derive_perpetual).

agents/smart_money_flow/ — AGENT.md, strategies/derive_flow_trader/
(strategy.md + 50-USDC test-mode config), routines/onchain_flow.py
(CoinGecko + GeckoTerminal keyless signal), skills/smart_money_playbook/,
HOW_IT_WORKS.md, validation.md
Flow composite: risk regime (mcap momentum, BTC dominance) + per-asset
flow intensity (vol/mcap, 24h change, trending) + Solana on-chain pulse
Decision matrix: LONG (RISK-ON + flow ≥ +0.4), SHORT (RISK-OFF + flow ≤ −0.4),
else HOLD — no forced trades
Execution: Derive perps, USDC-quoted (SOL/ETH/BTC-USDC), bounded sizing
(max 20 USDC/position, 2x, 1 position, 50-USDC wallet)
LLM: opencode-go:deepseek-v4-flash (cheap; ~$0.10–0.35/day at 300s cadence)

Depends on

Requires the opencode-go / deepseek provider from PR #170 (the agent's
agent_key uses opencode-go:deepseek-v4-flash). This PR is agent-only;
provider infra lands separately in #170.

Validation

Live on Derive mainnet (tiny ~55 USDC wallet): engine ticks, reads live
data, returns HOLD in current RISK-OFF regime (correct — no signal ≥ ±0.4)
Manual SOL-USDC LONG placed + closed end-to-end (fees ~$0.02), proving the
Derive execution path works
Frontend: rebuilt dist; strategy detail route loads (was a stale bundle +
folder/slug mismatch — both fixed)

Notes

Tested on Derive mainnet only (other perp venues untested by design)
Condor UI filters testnet connectors, so validation is mainnet-with-small-size

📸 Screenshots attached: Agents tab (Live), strategy detail, onchain_flow report.

Directional perp agent driven by a capital-flow & positioning composite: cross-market risk regime (CoinGecko /global + /coins/markets + /search/trending) plus an on-chain Solana DeFi pulse (GeckoTerminal SOL top pools). The routine produces a LONG/SHORT/HOLD signal; execution is venue-agnostic (Derive, Hyperliquid, Backpack, Pacifica, ...) via default_trading_context + Hummingbot server — the routine never calls an exchange API. - agents/smart_money_flow/AGENT.md: identity, opencode-go:deepseek-v4-flash - routines/onchain_flow.py: keyless signal fetch + scoring + ReportBuilder - strategies/directional_flow/strategy.md: directional perp playbook, risk limits - skills/smart_money_playbook/SKILL.md: flow decision matrix Verified: routine compiles and scores correctly live (RISK-OFF -> HOLD; forced RISK-ON +6.5% -> LONG +0.80; RISK-OFF -9.5% -> SHORT -0.40). Pivoted from Orca Whirlpools spot (CLMM cannot express directional/short).

…alidation runbook - strategy.md default_trading_context now names derive_perpetual as the concrete venue, documents the one-time 'connect derive_perpetual' step (Condor/API does NOT add keys by design), and gates mainnet behind derive_perpetual_testnet. - validation.md: testnet-first runbook proving execution before PR submission (connect once in client; Condor/API drives the connected instance).

…or code Verified against repo: - API keys are added ONLY via web dashboard (Settings -> Keys); Telegram /keys is read-only; MCP API does not add keys. - Condor web filters out testnet connectors (condor/web/routes/settings.py: 'testnet' not in c.lower()), so derive_perpetual_testnet is NOT selectable. Validation must be mainnet derive_perpetual on a tiny isolated wallet. Updated validation.md and strategy.md default_trading_context accordingly.

Cap budget at 50 USDC total: total_amount_quote 50, max_total_exposure_quote 50, max_position_size_quote 20, min_order_amount_quote 10, single position (max_open_executors 1), 2x leverage (~40 USDC notional, under balance). Keep production defaults documented separately. Aligns strategy.md + HOW_IT_WORKS.md.

…-USDC Derive perpetuals are quoted in USDC (trading-rule map + order-book subscription both require '-USDC'), not USDT. Correct default_trading_context pairs and the validation note accordingly.

…t result Restarting hummingbot-api repopulates the derive_perpetual symbol map after a bad-pair attempt (SOL-USDT) poisons it. Golden rules: use SOL/ETH/BTC-USDC on Derive; restart container if create_executor hangs with KeyError. Records the verified LONG SOL-USDC place+close on Derive mainnet (~$0.02 fees).

AGENT.md now states tested on Derive mainnet only (removed other DEXes from description/body). HOW_IT_WORKS.md adds concise LLM-per-tick cost note: deepseek-v4-flash pricing, prompt-cache effect, ~$0.10/day typical at 300s cadence.

…w_trader) The strategy folder was named 'directional_flow' while the strategy name 'Derive Flow Trader' slugifies to 'derive_flow_trader'. The web GET /agents/{slug}/strategies/{sslug} resolves by folder name, so the frontend (open button) passed the slug 'derive_flow_trader' and got 404 'Strategy not found'. Moved strategy.md into the slug-named folder and removed the stale directional_flow folder. Also tightened the description to Derive-only (remove Hyperliquid/Backpack/Pacifica per user request). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…s in onchain_flow - AGENT.md when_to_consult tightened to Derive perps (drop 'any venue'). - onchain_flow.py: report pair labels SOL/ETH/BTC now show -USDC to match Derive's USDC-quoted perps (signal is venue-independent; the displayed label was stale USDT). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

… prevent frontmatter truncation The '# --- ... ---' comment inside default_config ended YAML frontmatter at the first '---', silently dropping risk_limits / sizing / trading_context. The running engine then fell back to unsafe engine defaults. The fix removes the dashes from the comment.

…m for opencode-go model Switches agent_key from 'opencode-go:deepseek-v4-flash' to 'custom@opencode:deepseek-v4-flash' so the agent runs on opencode-go via PR hummingbot#175's named custom OpenAI-compatible endpoint (no PR hummingbot#170 needed). Documents endpoint setup: Settings -> LLM Endpoints, or CUSTOM_LLM_BASE_URL/CUSTOM_LLM_API_KEY in .env for headless condor-bot.service deploys.

rapcmia

Tested using binance perpetual only
Smart-Money Flow agent was consulted / delegated successfully
A local Binance dormant strategy was created with the Smart-Money Flow routine embedded. Its dry-run tick called onchain_flow, returned HOLD, and saved a dashboard for review.
When the market signal did not meet the entry rules, the strategy stayed out of the market and opened no executor, order, or position.
Observation snapshots were created

How to use it:
Consult and delegate Smart-Money Flow, then create a strategy for a supported perpetual account and run an observation or dry-run tick. The routine saves a dashboard with the flow decision. When it returns HOLD, the strategy safely waits and does not create an executor until both the regime and flow rules allow an entry.

fengtality · 2026-08-05T23:06:40Z

@carlito-hummingbot or @rapcmia please test this on Derive before next Tues.

Don't merge this in - I'll try to build an agent similar to it during the Derive workshop, and we can merge it in afterwards.

greptile-apps · 2026-08-10T14:27:17Z

Greptile Summary

The PR adds a Smart-Money Flow agent that combines CoinGecko market data with a GeckoTerminal Solana pulse and translates the result into Derive perpetual-futures instructions.

Adds asynchronous market and on-chain data collection, composite scoring, verdict formatting, and ReportBuilder output.
Adds a Derive strategy configuration and playbook for bounded LONG, SHORT, and HOLD decisions.
Adds agent-level operating, position-management, and journaling guidance.

Confidence Score: 3/5

The PR should not merge until the advertised leverage and exposure limits are enforceable and regime-aligned signals are selected across all eligible assets.

The current configuration silently drops two stated hard risk limits, including leverage despite simultaneous instructions permitting higher leverage, and the verdict algorithm can return HOLD when another asset satisfies the documented entry matrix.

Files Needing Attention: agents/smart_money_flow/strategies/derive_flow_trader/strategy.md, agents/smart_money_flow/AGENT.md, agents/smart_money_flow/routines/onchain_flow.py

Important Files Changed

Filename	Overview
agents/smart_money_flow/routines/onchain_flow.py	Adds the complete signal pipeline and reporting routine, but its absolute-score-first selection can suppress an otherwise eligible regime-aligned asset.
agents/smart_money_flow/strategies/derive_flow_trader/strategy.md	Adds Derive execution defaults and risk instructions, including leverage and total-exposure fields that the current risk model does not enforce.
agents/smart_money_flow/AGENT.md	Defines the agent workflow and position management, but permits looser leverage and concurrency than the strategy's small-wallet configuration.
agents/smart_money_flow/skills/smart_money_playbook/SKILL.md	Documents the composite, decision matrix, supported venues, and risk playbook consistently with the intended strategy.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    CG[CoinGecko global, markets, trending] --> Score[Regime and per-asset flow scoring]
    GT[GeckoTerminal SOL pools] --> Pulse[Solana on-chain pulse]
    Score --> Verdict{Regime-aligned flow?}
    Pulse --> Report[Flow report]
    Verdict -->|RISK-ON and positive| Long[LONG candidate]
    Verdict -->|RISK-OFF and negative| Short[SHORT candidate]
    Verdict -->|Otherwise| Hold[HOLD]
    Long --> Derive[Derive perpetual executor]
    Short --> Derive
    Report --> Agent[Smart-Money Flow agent]

_{Reviews (1): Last reviewed commit: "Delete agents/smart_money_flow/validatio..." | Re-trigger Greptile}

greptile-apps · 2026-08-10T14:27:20Z

+    max_open_executors: 1           # one position at a time on a tiny wallet
+    max_leverage: 2                  # 2x keeps notional ~40 USDC (< balance)


Risk limits are silently discarded

When the model creates an executor above 2x leverage or the intended 50 USDC aggregate exposure, RiskLimits.from_dict discards max_leverage and max_total_exposure_quote, so the advertised hard limits do not reject the executor and the mainnet wallet can take more exposure than configured.

greptile-apps · 2026-08-10T14:27:20Z

+    best = assets_out[0] if assets_out else None
+    direction = "HOLD"
+    rationale = "no decisive flow"
+    if best and abs(best["flow_score"]) >= 0.4 and regime["label"] != "NEUTRAL":
+        if best["flow_score"] > 0 and regime["label"] == "RISK-ON":
+            direction = "LONG"
+            rationale = "RISK-ON + positive flow"


Absolute ranking suppresses valid signals

When the largest-magnitude flow conflicts with the regime while another asset clears the aligned threshold, the routine evaluates only assets_out[0] and returns HOLD, causing the strategy to miss a qualifying LONG or SHORT signal.

Carlito and others added 12 commits July 28, 2026 23:01

docs(smart-money-flow): add HOW_IT_WORKS — workflow + scoring + setup

aa3de77

fix(smart-money-flow): Derive perps are USDC-quoted — use SOL/ETH/BTC…

eab5b91

…-USDC Derive perpetuals are quoted in USDC (trading-rule map + order-book subscription both require '-USDC'), not USDT. Correct default_trading_context pairs and the validation note accordingly.

rapcmia approved these changes Aug 4, 2026

View reviewed changes

cardosofede added 2 commits August 10, 2026 17:23

Delete agents/smart_money_flow/HOW_IT_WORKS.md

4f0087c

Delete agents/smart_money_flow/validation.md

7995dd0

cardosofede approved these changes Aug 10, 2026

View reviewed changes

cardosofede merged commit 3abbd8a into hummingbot:main Aug 10, 2026
1 check passed

greptile-apps Bot reviewed Aug 10, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat(agents): Derive Perp Smart-Money Flow Agent - #178

feat(agents): Derive Perp Smart-Money Flow Agent#178
cardosofede merged 14 commits into
hummingbot:mainfrom
carlito-hummingbot:feat/smart-money-flow-agent

carlito-hummingbot commented Jul 28, 2026

Uh oh!

rapcmia left a comment

Uh oh!

fengtality commented Aug 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

greptile-apps Bot commented Aug 10, 2026

Important Files Changed

Flowchart

Uh oh!

greptile-apps Bot Aug 10, 2026

Uh oh!

greptile-apps Bot Aug 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		max_open_executors: 1 # one position at a time on a tiny wallet
		max_leverage: 2 # 2x keeps notional ~40 USDC (< balance)

Uh oh!

Conversation

carlito-hummingbot commented Jul 28, 2026

Summary

Depends on

Validation

Notes

Uh oh!

rapcmia left a comment

Choose a reason for hiding this comment

Uh oh!

fengtality commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot commented Aug 10, 2026

Greptile Summary

Confidence Score: 3/5

Important Files Changed

Flowchart

Uh oh!

greptile-apps Bot Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

fengtality commented Aug 5, 2026 •

edited

Loading