feat(agents): scaffold delta-neutral funding carry agent

[david-hummingbot]

Adds funding_carry_expert with the spot_perp_carry strategy: long spot, short perp, matched notional, on a single venue. Price moves cancel between the legs, so the entire return is the funding the short leg collects.

Ships as dry_run, $200 default, 3600s ticks. Additive only — no existing behaviour touched.

Why this strategy

Validated on 90 days of Bitget funding history (BTC/ETH/XRP/SOL/DOGE/LINK): funding is positive 69–79% of periods with P(pos|pos) of 77–88%. That persistence is what makes it a carry you hold rather than a spread you chase — and is exactly why the cross-venue differential version failed while this one doesn't.

Expected net: 1–4% APR on majors, ~10% on screened names. Modest, and stated plainly in the docs rather than dressed up.

Three findings encoded in the scaffold

Never gate on funding sign

The intuitive move — close when funding turns negative — destroys the strategy:

pair	buy-and-hold	closing on sign flips
BTC	+46 bps	−371 bps
ETH	+79 bps	−168 bps
XRP	+53 bps	−213 bps
LINK	+85 bps	−322 bps

Funding flips sign 52–93 times per 270 periods, but negative prints are tiny — each exit pays ~21 bps to dodge a fraction of one. This appears in AGENT.md, strategy.md, and the deploy skill, because an LLM's instinct is to actively manage the position and here that instinct is the primary failure mode. The strategy's decision table answers "HOLD" to five separate alarming-looking observations.

A spot market is a hard requirement, enforced in code

Screening all Bitget perps causally (side chosen from a trailing window, then forward funding collected):

universe	median annualised net
All high-carry names	−2.6%
Names with a spot market	+10.6%

Spot-listed names showed 72–100% hit rates with 1–2 side changes over ~99 days. Non-spot names showed 7–45% with 16–44 changes — funding that flips constantly and churns fees into a loss. Without a spot leg there is no hedge, so it is a naked perp rather than a carry.

require_spot defaults true and the docs say never to disable it. The screener also reports rejected unstable names with their negative hold-net — those are the highest-funding symbols on the board, so surfacing them stops the agent rediscovering them as opportunities.

Size on the trailing mean, never a snapshot

One live XRP funding print annualised to ~7.8%; the 90-day mean was nearer 3%. The screener emits both funding_now_bps and funding_mean_bps and the strategy is instructed to size from the mean.

shutdown.md inverts the framework default

Uses flatten_all rather than keep_spot_close_perp. The default would close the hedge and leave a naked long — for a strategy whose entire safety property is neutrality, that is the worst available outcome. Both legs go together, perp first to shed liquidation risk.

Consequence documented: use shutdown, not plain stop, when positions are open, or the API returns 409.

Known limitations

• Returns are small in absolute terms: at $200 and 3% APR, roughly $6/year. Worth running small to learn two-leg coordination safely, not for income.
• The ~10% figure rests on n=4 spot-listed high-carry names in a single snapshot; the universe rotates.
• Extreme funding often signals distress (low float, delisting risk). The stability filter helps but does not eliminate it.
• 90 days of history per name; longer regimes aren't captured.
• Do not extend this to cross-venue — that variant was tested and failed.