feat: hackathon sample agents by fengtality · Pull Request #216 · hummingbot/condor

fengtality · 2026-08-21T14:27:39Z

Sample agents for the hackathon, split out of #204 so that PR carries no agents/ diff. Stacked on #204.

New agent

Derive Options Trader — directional perp trader on derive_perpetual. Renamed from smart_money_flow, which is deleted here; onchain_flow.py moves across unchanged (R100) and smart_money_playbook/SKILL.md mostly so (R076).


`routines/options_flow.py`	Derive options market read → directional signal for SOL-PERP, across all active expiries
`routines/onchain_flow.py`	Solana on-chain capital-flow pulse
`strategies/options_oracle_operator`	Trades SOL-USDC perps off the `options_flow` signal — 25D risk reversal
`strategies/smart_money_flow`	Cross-market flow + regime, confirmed against Derive options positioning; bounded leverage

Extensions to existing agents

Adaptive Grid Trader — a Kalman-filter regime layer over the grid.


`routines/kalman_regime_check.py`	Regime, SNR and grid width from the filtered state
`routines/kalman_grid_operator.py`	Operator loop that deploys, retunes, profit-takes or flips one grid
`strategies/kalman_grid_btc`	BTC-USDT on `bitget_perpetual` — $90 of a $100 budget, 5x, 10% max loss

Market Making Expert


`strategies/sndk_gate_hft_mm`	Asymmetric PMM on SNDK-USDT perp, built around the Gate.io pro maker rebate

Meteora Launch LP — Alpha Vault (rate-limiter) pools as a fee-yield venue.


`routines/damm_v2_rate_limiter_scanner.py`	Scans DAMM v2 pools with an active Alpha Vault
`strategies/rate_limiter_lp_operator`	LPs into them — the vault throttles bots, so fee flow is cleaner
`launch_safety_check` (routine + skill), `launch_lp_operator`, `AGENT.md`	Updated alongside

Solana DEX LP Expert — lp_range_config and AGENT.md, from a live incident.

The skill documented only lp_executor's separate base_amount/quote_amount. An agent asked to run the lp_rebalancer controller read that table and carried the two-amount model into a tool that takes a single total_amount_quote and splits it itself, deploying a bot at half the intended size. Three differences, verified against _calculate_amounts and _calculate_price_bounds:

total_amount_quote is the whole position. On side=3 RANGE the split is a hard 50/50, so deploying a base holding B needs 2·B·P.
position_width_pct is a FULL width — 5 gives ±2.5%.
position_offset_pct is a rebalance setting. side applies only to the first position; after that the controller always picks BUY or SELL, and RANGE ignores the offset while BUY/SELL do not. So the field has no effect on the position being configured and governs every one after it — where a negative value forces a two-sided re-open the wallet cannot fund, because a top-exit close returns 100% quote. Keep it positive.

That last one cost a live bot 29 failed opens (64 SLIPPAGE_EXCEEDED, 54 INSUFFICIENT_BALANCE).

Notes for review

Four P1s from review, all fixed in kalman_grid_operator — and all confirmed against the running stack rather than read:

search_executors returns hapi's {"data": …, "pagination": …} envelope, so for e in execs walked its string keys and threw AttributeError every monitoring tick — swallowed as a warning, leaving the grid running with no PnL updates, stale detection, profit-taking or flips. Now goes through extract_executors_list, as every other consumer does.
_teardown logged a warning on failure and the caller redeployed regardless, so a failed stop left the original leveraged grid live and untracked beside a second full-budget one. It returns a bool now, and that bool is only true once the executor is confirmed gone from the active list.
Cancelling the routine left the grid trading for the rest of its 24h lifetime. It now stops the grid, and says so loudly when it cannot.

The Gate market-analysis skills are not here. Both copies were removed — gate-exchange-marketanalysis (with its references/ and setup.sh) and the underscored duplicate. sndk_gate_hft_mm was their only consumer and is kept, with its two references rewritten rather than deleted: the pre-flight now names the three inputs directly (14d candles for volatility and trend, an order-book snapshot for depth, funding rate for sell-side skew) and points at the strategy's own Regime Adaptation table, which keeps the regime vocabulary the skill defined.

No XRPL strategy under Market Making Expert. The standalone xrpl_market_maker agent already covers XRP-USDC on the XRPL DEX. That agent predates this branch, so dropping the duplicate here leaves it untouched rather than deleting base content.

No tests for sample agents. The one test in tests/ that imported from agents/ is deleted rather than carried here, since these agents may be removed. The rest of test_orphan_visibility_fixes.py stays on #204 — despite the filename those tests exercise condor/agents/, the framework, not agents/, the samples.

Known overlap, for the role revision

lp_range_config currently documents two different tools in one file — lp_executor and the lp_rebalancer controller. That collision is what caused the incident above. If the role split separates "runs executors" from "runs controllers", this skill likely wants splitting along the same line.

21 files, every one under agents/. Full suite passes (2550), black --check clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_0166iQoxKce23GkUwuQJxdkr

…tor's Lifted out of feat/lp-close-retry-ownership so that PR carries no agents/ diff. Content is unchanged from that branch; this is the same work on a base that makes it reviewable on its own. The substantive part is lp_range_config. An agent asked to run lp_rebalancer read the skill's amounts table -- which is written for lp_executor's separate base_amount/quote_amount -- and carried that model into the controller, which takes a single total_amount_quote and splits it itself. On side=3 RANGE that split is a hard 50/50, so sizing the total at B*P deploys half the intended base. Two neighbouring fields mislead the same way: position_width_pct is a FULL width there (5 means +/-2.5%), and position_offset_pct is ignored entirely on RANGE, so a small negative offset 'to stay in range' is a no-op. All three verified against _calculate_amounts and _calculate_price_bounds. Also names the controllers the consult routing covers, and restores the agents/ work this branch's sibling had to set aside: the Derive Options Trader rename and its routines, the kalman grid strategy, the gate market-analysis skills and the meteora rate-limiter scanner. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

greptile-apps · 2026-08-21T14:33:31Z

Greptile Summary

The PR adds hackathon sample agents and strategies for options-driven perpetual trading, Kalman-managed grids, market making, and Solana liquidity provision, while updating supporting agent guidance.

Adds Derive options and Solana flow routines with directional perpetual strategies.
Adds a continuous Kalman grid operator and regime-analysis routine.
Extends Meteora launch-LP workflows and LP-controller configuration guidance.
Updates shared executor-volume documentation and the dependency lockfile.

Confidence Score: 3/5

The PR does not appear safe to merge until grid replacement and cancellation verify that the executor is terminated and its exchange position is flat.

The revised teardown still equates absence from the active-executor list with position closure, and the cancellation path still reports a successful stop after one non-raising request; both paths can leave residual leveraged exposure untracked.

Files Needing Attention: agents/adaptive_grid_trader/routines/kalman_grid_operator.py

Important Files Changed

Filename	Overview
agents/adaptive_grid_trader/routines/kalman_grid_operator.py	Adds the continuous Kalman grid lifecycle, monitoring, retuning, teardown, and cancellation logic.
agents/derive_options_trader/routines/options_flow.py	Adds Derive options aggregation and directional signal generation across active expiries.
agents/meteora_launch_lp/routines/damm_v2_rate_limiter_scanner.py	Adds discovery and ranking of DAMM v2 pools with active Alpha Vault rate limiters.
condor/fetchers/executors.py	Clarifies that filled quote amount is the canonical traded-volume field for executor types including LP.
uv.lock	Refreshes locked package artifacts without changing the reviewed runtime workflows.

_{Reviews (12): Last reviewed commit: "docs(executors): say that filled_amount_..." | Re-trigger Greptile}

greptile-apps · 2026-08-21T14:33:34Z

+if command -v shasum > /dev/null 2>&1; then
+  (cd "$TMP" && echo "$CHECKSUM_LINE" | shasum -a 256 --check --status)
+elif command -v sha256sum > /dev/null 2>&1; then
+  (cd "$TMP" && echo "$CHECKSUM_LINE" | sha256sum --check --status)
+else
+  echo "Warning: no sha256sum or shasum found, skipping checksum verification" >&2
+fi


Missing checksum tools bypass verification

If the installation host lacks both shasum and sha256sum, this branch skips verification and continues to extract and install the downloaded executable, allowing a corrupted or attacker-supplied archive to run as host code. Fail closed instead of installing when integrity cannot be checked.

How this was verified: The missing-tool branch explicitly skips verification before the script continues into extraction and installation.

test_confidence_is_graded_against_the_emitted_direction imports agents.derive_options_trader.routines.options_flow, which lives on this branch, so the test belongs here too. It is the only test in tests/ that reaches into agents/ — the path-based split left it importing a module its own branch no longer had. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The confidence test imported agents.derive_options_trader.routines.options_flow — a sample agent, which may be removed — so it is deleted outright rather than moved to this branch. The file's other two tests stay: despite the filename they exercise condor/agents/ (the framework: AgentPerformance, ExecutorsProvider, and format_clmm_result's snake_case position_info branch), not agents/ (the samples). Deleting the file wholesale would have regressed framework coverage this PR's base depends on. This branch now leaves the file untouched. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Removes both copies of the Gate market-analysis skill — gate-exchange-marketanalysis (hyphenated, with its references/ and setup.sh) and gate_exchange_marketanalysis (the underscored duplicate) — along with the sndk_gate_hft_mm strategy that was their only consumer. Nothing outside the removed directories referred to them: the sole cross-reference was sndk_gate_hft_mm -> gate_exchange_marketanalysis, and both go together. market_making_expert/AGENT.md names pmm_mister_deploy, not these. Left alone: orca_lp_expert/skills/add_token_to_gateway, which matches 'gate' only because it is about Gateway. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The strategy comes back; the Gate market-analysis skills do not. Its two references to gate_exchange_marketanalysis are replaced rather than deleted, since the checks behind them are real: the pre-flight now names the three inputs directly (14d candles for volatility and trend, an order-book snapshot for depth at the quoted levels, funding rate for sell-side skew) and points at this file's own Regime Adaptation table, which keeps the regime vocabulary the skill defined. Only strategy.md is tracked — sessions/ is gitignored, so the session snapshots that still name the old skill stay local. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…#204

…rphaning live grids All four confirmed against the running stack, not just read. 1. search_executors returns hapi's {'data': [...], 'pagination': {...}} envelope (verified live), so 'for e in execs' walked its string keys and e.get() threw AttributeError on every monitoring tick. The tick handler swallowed it as a warning, leaving the grid running with no PnL updates, stale detection, profit-taking, retuning or flips. Now goes through condor.fetchers.executors.extract_executors_list, as every other consumer in the repo does. 2. _teardown logged a WARN and returned on failure, and the caller cleared executor_id and deployed regardless — so a failed stop left the original leveraged grid live and untracked while a second full-budget grid traded beside it. It now returns a bool and the caller holds on false. 3. That bool is only true once the executor is confirmed gone from the active list. A stop the venue did not honour, or that could not be verified, counts as still running: better a missed retune than doubled exposure. 4. The CancelledError handler wrote its final report and returned without stopping the grid, so stopping the operator left it trading for the rest of its 24h lifetime with nobody monitoring it. It now stops the grid, and says loudly in the log and the report when it could not. client is bound to None before the loop — the new handler touches it, and cancellation can arrive before the first tick assigns it. The fifth comment, on gate-exchange-marketanalysis/setup.sh, is moot: that skill was removed from this PR. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…ex.html

…nk ones xrpl_xrpusdc_mm_operator is removed from market_making_expert: the standalone xrpl_market_maker agent already covers XRP-USDC on the XRPL DEX, and that agent predates this branch, so removing the duplicate here leaves it untouched rather than deleting base content. Only strategy.md was tracked; sessions/ and learnings.md are gitignored and stay local. kalman_grid_btc and sndk_gate_hft_mm both shipped with description: '', which renders as a blank card in the agent view. Both now describe what they trade and on what basis. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…consult routing Moved here from #204: this belongs with the sample agents, which are about to be revised so each occupies a distinct role. lp_range_config previously documented only lp_executor's separate base_amount/quote_amount. An agent asked to run the lp_rebalancer CONTROLLER read that table and carried the two-amount model into a tool that takes a single total_amount_quote and splits it itself, deploying a bot sized at half the intended base. Three ways the controller differs, verified against _calculate_amounts and _calculate_price_bounds: - total_amount_quote is the whole position. On side=3 RANGE the split is a hard 50/50, so deploying a base holding B needs 2*B*P. - position_width_pct is a FULL width -- 5 gives +/-2.5%. - position_offset_pct is a REBALANCE setting. side applies only to the first position; after that the controller always picks BUY or SELL, and RANGE ignores the offset while BUY/SELL do not. So the field has no effect on the position being configured and governs every one after it, where a negative value forces a two-sided re-open the wallet cannot fund: a top-exit close returns 100% quote. Keep it positive. AGENT.md names the controllers the consult routing covers — the incident that prompted this skipped consult entirely and went straight to raw tools. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

agents/condor/AGENT.md advertised 10 of the 13 registered mcp-hummingbot tools. manage_clmm, manage_gateway_swaps and configure_server were absent, so the agent whose instructions this file *is* had no reason to know they existed — it listed manage_amm but not its concentrated-liquidity counterpart, and no swap tool at all. manage_executors now also says it is how you swap on a DEX, and the manage_gateway_swaps entry says to prefer order_executor for a swap inside a strategy. Same correction as the tool docstrings, at the layer the agent reads first. Verified by diffing the file's tool names against the @mcp.tool functions in server.py: 13 registered, 0 missing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Adding it was wrong: leaving it out is deliberate, so the agent reaches for manage_executors instead. Removed. Worth recording why that omission did not hold. The list in this file is prose, not an allowlist. Enforcement is the tools: frontmatter key — sessions.py passes allowed_tools=bound.tools or None, so an agent WITH that key is restricted to it (market_making_expert lists 11, which is the count the UI shows) and an agent WITHOUT it gets None, meaning every registered MCP tool. This file has no tools: key, so all 13 mcp-hummingbot tools were in the model's schema list regardless of what the prose named — including manage_gateway_swaps, whose own docstring then claimed to be 'the ONLY swap surface'. manage_clmm and configure_server stay listed: those two were simply absent, and the file already named manage_amm without its concentrated-liquidity counterpart. manage_executors now also says it is how to swap on a DEX, which is the behaviour the omission was reaching for. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…executors The list named 10 of the 13 registered mcp-hummingbot tools. Omitting manage_gateway_swaps was meant to keep the agent on manage_executors, but the omission has no force: this file has no tools: frontmatter key, so sessions.py passes allowed_tools=None and every registered tool is in the model's schema list anyway — manage_gateway_swaps included, with its own docstring then claiming to be 'the ONLY swap surface'. An agent asked to swap found the tool, believed the docstring, and used it. So the three missing tools are listed, and the two that have an executor equivalent say to use it: manage_clmm defers to lp_executor, manage_gateway_swaps to order_executor, each with the narrow cases where the direct tool is still the right call (inspect or recover a position, create a pool; a quote with no execution, history, an unrouted connector). manage_executors itself now names both paths and why they matter — the slippage ramp and the controller_id tag that PnL attribution keys on, neither of which a direct call carries. Steering beats omission here: a tool the model can see will be used, so the list has to say what to use instead rather than pretend the tool is absent. Verified against the @mcp.tool functions in server.py: 13 registered, 0 missing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

… re-lock

get_executor_volume already preferred filled_amount_quote, so the dashboard needed no change -- but what that field MEANS did. An LP executor used to report the capital it deposited there, so the dashboard showed a position's deposit as its volume; it now reports the swaps that crossed its range, derived from the fees it earned. Same code, correct number. Says so at the function, since the reason to reach for a different field is now gone and the next reader should not go looking for one. Also re-locks the client for its matching docstring fix (hummingbot-api-client ee667f2).