基差套利

• ✓任何行情都可运行，收益相对稳但空间小
• ⚠极端行情下价差/费率可能异常放大

回测曲线为确定性模拟价格路径上的示例，非真实收益。

"""基差套利（Basis trade / cash-and-carry）—— 永续-现货基差收敛。

思路：永续价格显著升水现货（基差 > entry_bps）时空永续 + 多现货，赚基差收敛 + 空头资金费；显著
贴水（基差 < -entry_bps）时镜像。基差收敛到 exit_bps 以内平掉双腿。期现套利（cash-and-carry）的
永续版，市场中性。
参数：entry_bps（进场基差，基点）、exit_bps（离场基差，基点）、size（单腿数量）。

降级行为：feed 未提供现货腿行情、或连接器不支持做空时保持空仓（拒绝裸敞口）。实盘单一 venue 需
场馆支持现货腿或由操盘手在外部对冲。
"""
from __future__ import annotations

from ..base import StrategyBase
from ..context import StrategyContext
from ..registry import register


@register("基差套利")
class BasisTrade(StrategyBase):
    description = "基差超 entry_bps 空永续/多现货，收敛到 exit_bps 平仓；期现 carry。"
    params = {"entry_bps": 20.0, "exit_bps": 5.0, "size": 4.0}

    def __init__(self, entry_bps: float = 20.0, exit_bps: float = 5.0, size: float = 4.0) -> None:
        self.entry_bps = float(entry_bps)
        self.exit_bps = float(exit_bps)
        self.size = float(size)

    async def on_tick(self, ctx: StrategyContext) -> None:
        sym = ctx.conn_symbol()
        pair = ctx.pair_symbol()
        if pair is None or not getattr(ctx.conn, "allow_short", False):
            return  # 无法构成对冲：保持空仓
        perp = await ctx.price(sym)
        spot = await ctx.price(pair)
        if not spot:
            return
        basis_bps = (perp - spot) / spot * 1e4
        band = self.size * 0.1
        if basis_bps > self.entry_bps:
            await ctx.target(sym, -self.size, band=band)   # 升水：空永续
            await ctx.target(pair, self.size, band=band)   # 多现货
        elif basis_bps < -self.entry_bps:
            await ctx.target(sym, self.size, band=band)    # 贴水：多永续
            await ctx.target(pair, -self.size, band=band)
        elif abs(basis_bps) < self.exit_bps:
            await ctx.target(sym, 0.0, band=band)
            await ctx.target(pair, 0.0, band=band)

完整 SDK 与全部策略以 MIT 协议开源，可直接回测、paper 试跑或二次开发。