exchange.GetFundingHistory()

获取合约历史资金费率数据（仅限合约交易）。

语法

python

# 使用默认参数（使用交易所设置的币种，返回最近21条）
history = exchange.GetFundingHistory()

# 指定币种，获取最近100条资金费率
history = exchange.GetFundingHistory("BTC_USDT", 100)

# 获取指定时间范围的资金费率
from datetime import datetime, timedelta

end_time = int(datetime.now().timestamp() * 1000)
start_time = int((datetime.now() - timedelta(days=7)).timestamp() * 1000)
history = exchange.GetFundingHistory("BTC_USDT", 1000, start_time, end_time)

参数

参数	类型	必填	说明
symbol	str	否	合约代码（格式，如 "BTC_USDT"），不传则使用交易所设置的币种
limit	int	否	返回数量，默认21，最大1000
start_time	int	否	开始时间（毫秒时间戳）
end_time	int	否	结束时间（毫秒时间戳）

注意：

不传任何参数时，使用交易所默认币种，返回最近21条数据（约7天历史）
如果未设置 start_time 和 end_time，返回最近的 limit 条数据
币安支持时间范围查询（最多200天），Gate 仅支持 limit 限制
资金费率通常每8小时结算一次（00:00、08:00、16:00 UTC）

返回值

返回一个列表，每个元素包含以下字段：

字段	类型	说明
Symbol	str	合约代码（格式，如 "BTC_USDT"）
FundingTime	int	资金费率结算时间（毫秒时间戳）
FundingRate	float	资金费率（浮点数，如 0.0001 表示 0.01%）
MarkPrice	float	标记价格（币安提供，Gate 为 0）
Info	dict	交易所原始数据

支持的交易所

✅ Binance Futures（币安合约）- 支持时间范围查询
✅ Gate.io Futures（Gate.io 合约）- 仅支持 limit 限制
❌ 现货交易所不支持此方法

示例

1. 获取最近的资金费率历史

python

# 使用默认参数（交易所默认币种，最近21条）
history = exchange.GetFundingHistory()

for item in history:
    from datetime import datetime
    funding_time = datetime.fromtimestamp(item['FundingTime'] / 1000)
    rate_percent = item['FundingRate'] * 100
    print(f"{funding_time} | 费率: {rate_percent:.4f}%")

# 指定币种，获取最近100条BTC资金费率
history = exchange.GetFundingHistory("BTC_USDT", 100)

for item in history[:5]:  # 显示前5条
    from datetime import datetime
    funding_time = datetime.fromtimestamp(item['FundingTime'] / 1000)
    rate_percent = item['FundingRate'] * 100
    
    print(f"{funding_time} | 费率: {rate_percent:.4f}% | 标记价: ${item['MarkPrice']:.2f}")

# 输出示例:
# 2025-01-10 16:00:00 | 费率: 0.0100% | 标记价: $94526.30
# 2025-01-10 08:00:00 | 费率: 0.0100% | 标记价: $94231.50
# 2025-01-10 00:00:00 | 费率: 0.0100% | 标记价: $93845.20

2. 获取指定时间范围的资金费率

python

from datetime import datetime, timedelta

# 获取最近7天的资金费率
end_time = int(datetime.now().timestamp() * 1000)
start_time = int((datetime.now() - timedelta(days=7)).timestamp() * 1000)

history = exchange.GetFundingHistory("BTC_USDT", 1000, start_time, end_time)

print(f"获取到 {len(history)} 条历史记录")
# 输出: 获取到 21 条历史记录 (7天 × 3次/天)

3. 计算平均资金费率

python

# 获取最近30天的资金费率并计算统计数据
from datetime import datetime, timedelta

end_time = int(datetime.now().timestamp() * 1000)
start_time = int((datetime.now() - timedelta(days=30)).timestamp() * 1000)

history = exchange.GetFundingHistory("BTC_USDT", 1000, start_time, end_time)

# 计算统计数据
rates = [item['FundingRate'] for item in history]
avg_rate = sum(rates) / len(rates)
max_rate = max(rates)
min_rate = min(rates)
positive_count = sum(1 for r in rates if r > 0)
negative_count = sum(1 for r in rates if r < 0)

print(f"📊 BTC资金费率统计（最近30天）:")
print(f"  平均费率: {avg_rate*100:.4f}%")
print(f"  最高费率: {max_rate*100:.4f}%")
print(f"  最低费率: {min_rate*100:.4f}%")
print(f"  正费率次数: {positive_count} ({positive_count/len(rates)*100:.1f}%)")
print(f"  负费率次数: {negative_count} ({negative_count/len(rates)*100:.1f}%)")

# 输出示例:
# 📊 BTC资金费率统计（最近30天）:
#   平均费率: 0.0095%
#   最高费率: 0.0150%
#   最低费率: -0.0020%
#   正费率次数: 87 (96.7%)
#   负费率次数: 3 (3.3%)

4. 跨交易所资金费率对比

python

# 对比币安和Gate的资金费率
binance_history = binance_exchange.GetFundingHistory("BTC_USDT", 10)
gate_history = gate_exchange.GetFundingHistory("BTC_USDT", 10)

print("📊 资金费率对比:")
print(f"{'时间':<20} | {'币安':<12} | {'Gate':<12} | {'差异':<10}")
print("-" * 70)

for b, g in zip(binance_history, gate_history):
    from datetime import datetime
    time_str = datetime.fromtimestamp(b['FundingTime'] / 1000).strftime('%Y-%m-%d %H:%M')
    b_rate = b['FundingRate'] * 100
    g_rate = g['FundingRate'] * 100
    diff = b_rate - g_rate
    
    print(f"{time_str} | {b_rate:>10.4f}% | {g_rate:>10.4f}% | {diff:>+9.4f}%")

# 输出示例:
# 📊 资金费率对比:
# 时间                  | 币安         | Gate        | 差异      
# ----------------------------------------------------------------------
# 2025-01-10 16:00 |     0.0100% |     0.0098% |   +0.0002%
# 2025-01-10 08:00 |     0.0100% |     0.0102% |   -0.0002%
# 2025-01-10 00:00 |     0.0100% |     0.0099% |   +0.0001%

5. 检测套利机会

python

# 检测资金费率套利机会
binance_history = binance_exchange.GetFundingHistory("BTC_USDT", 100)
gate_history = gate_exchange.GetFundingHistory("BTC_USDT", 100)

# 查找费率差异大于0.01%的时间点
arbitrage_opportunities = []
for b, g in zip(binance_history, gate_history):
    rate_diff = abs(b['FundingRate'] - g['FundingRate'])
    
    if rate_diff > 0.0001:  # 差异>0.01%
        from datetime import datetime
        time_str = datetime.fromtimestamp(b['FundingTime'] / 1000)
        
        arbitrage_opportunities.append({
            'time': time_str,
            'binance_rate': b['FundingRate'],
            'gate_rate': g['FundingRate'],
            'diff': rate_diff,
        })

if arbitrage_opportunities:
    print(f"💰 发现 {len(arbitrage_opportunities)} 次套利机会:")
    
    for opp in arbitrage_opportunities[:5]:  # 显示前5次
        print(f"  {opp['time']} | 差异: {opp['diff']*100:.4f}%")
        print(f"    币安: {opp['binance_rate']*100:.4f}% | Gate: {opp['gate_rate']*100:.4f}%")
else:
    print("未发现明显套利机会")

6. 趋势分析

python

from datetime import datetime, timedelta

# 获取最近30天的数据
end_time = int(datetime.now().timestamp() * 1000)
start_time = int((datetime.now() - timedelta(days=30)).timestamp() * 1000)

history = exchange.GetFundingHistory("BTC_USDT", 1000, start_time, end_time)

# 按日期分组统计
daily_rates = {}
for item in history:
    date = datetime.fromtimestamp(item['FundingTime'] / 1000).strftime('%Y-%m-%d')
    
    if date not in daily_rates:
        daily_rates[date] = []
    
    daily_rates[date].append(item['FundingRate'])

# 计算每日平均费率
print("📈 每日平均资金费率趋势:")
for date in sorted(daily_rates.keys())[-7:]:  # 显示最近7天
    rates = daily_rates[date]
    avg = sum(rates) / len(rates)
    
    print(f"{date}: {avg*100:.4f}% (共{len(rates)}次结算)")

# 输出示例:
# 📈 每日平均资金费率趋势:
# 2025-01-04: 0.0092% (共3次结算)
# 2025-01-05: 0.0095% (共3次结算)
# 2025-01-06: 0.0098% (共3次结算)
# 2025-01-07: 0.0102% (共3次结算)
# 2025-01-08: 0.0105% (共3次结算)
# 2025-01-09: 0.0100% (共3次结算)
# 2025-01-10: 0.0098% (共3次结算)

7. 计算持仓成本

python

# 计算持有7天的资金费用成本
from datetime import datetime, timedelta

# 获取最近7天的资金费率
end_time = int(datetime.now().timestamp() * 1000)
start_time = int((datetime.now() - timedelta(days=7)).timestamp() * 1000)

history = exchange.GetFundingHistory("BTC_USDT", 1000, start_time, end_time)

# 假设持仓10万USDT
position_size = 100000  # USDT

# 计算累计费用
total_funding = 0
for item in history:
    funding_fee = position_size * item['FundingRate']
    total_funding += funding_fee

avg_rate = sum(item['FundingRate'] for item in history) / len(history)

print(f"💵 持仓成本分析（7天）:")
print(f"  持仓规模: ${position_size:,.0f}")
print(f"  结算次数: {len(history)}次")
print(f"  平均费率: {avg_rate*100:.4f}%")
print(f"  累计费用: ${total_funding:,.2f}")
print(f"  日均费用: ${total_funding/7:,.2f}")

# 输出示例:
# 💵 持仓成本分析（7天）:
#   持仓规模: $100,000
#   结算次数: 21次
#   平均费率: 0.0095%
#   累计费用: $199.50
#   日均费用: $28.50

数据格式差异

币安（Binance）

原始API返回：

json

[
  {
    "symbol": "BTCUSDT",
    "fundingTime": 1765440000000,
    "fundingRate": "-0.00001577",
    "markPrice": "90231.40000000"
  }
]

封装后返回：

python

[
  {
    'Symbol': 'BTC_USDT',           # 转换为XMX格式
    'FundingTime': 1765440000000,   # 毫秒时间戳
    'FundingRate': -0.00001577,     # 转换为浮点数
    'MarkPrice': 90231.40,          # 转换为浮点数
    'Info': {                       # 原始数据
      'symbol': 'BTCUSDT',
      'fundingTime': 1765440000000,
      'fundingRate': '-0.00001577',
      'markPrice': '90231.40000000'
    }
  }
]

特性：

时间戳：毫秒
支持时间范围查询（start_time 和 end_time）
提供标记价格（MarkPrice）
最多查询200天数据

Gate.io

原始API返回：

json

[
  {
    "r": "0.000014",    # 费率
    "t": 1765440000     # 时间戳（秒）
  }
]

封装后返回：

python

[
  {
    'Symbol': 'BTC_USDT',           # 传入的合约代码
    'FundingTime': 1765440000000,   # 转换为毫秒时间戳
    'FundingRate': 0.000014,        # 转换为浮点数
    'MarkPrice': 0,                 # Gate不提供，固定为0
    'Info': {                       # 原始数据
      'r': '0.000014',
      't': 1765440000
    }
  }
]

特性：

时间戳：秒（SDK已自动转换为毫秒）
仅支持 limit 限制，不支持时间范围查询
不提供标记价格（MarkPrice 固定为 0）
无时间范围限制，但只能取最近N条

关键差异：

Gate原始时间戳是秒，币安是毫秒（SDK已统一）
Gate不返回标记价格，SDK填充为 0
Gate字段极简（只有r和t），币安字段丰富

错误处理

python

try:
    history = exchange.GetFundingHistory("BTC_USDT", 100)
    
    if not history:
        print("未获取到历史数据")
    else:
        print(f"成功获取 {len(history)} 条记录")
        
except ValueError as e:
    print(f"参数错误: {e}")
    
except RuntimeError as e:
    print(f"运行时错误: {e}")
    
except Exception as e:
    print(f"未知错误: {e}")

常见问题

1. 为什么Gate的MarkPrice为0？

Gate.io API不提供历史标记价格，只有币安返回此字段。

2. 如何理解资金费率的正负？

正数：多方支付给空方（做多成本高，市场看涨）
负数：空方支付给多方（做空成本高，市场看跌）

3. 资金费率多久结算一次？

通常为每8小时一次（UTC时间 00:00、08:00、16:00），部分合约可能不同。

4. 如何计算资金费用？

plaintext

资金费用 = 持仓价值 × 资金费率

例如：持仓10万USDT，费率0.01%，则需支付10元资金费。

应用场景

资金费率套利 - 对比不同交易所的费率差异
持仓成本计算 - 评估长期持仓的资金费用
市场情绪分析 - 通过费率趋势判断市场多空情绪
策略回测 - 使用历史费率数据进行策略验证
风险管理 - 预测未来资金费用支出

注意事项

⚠️ 历史数据可能有延迟，实时性要求高的场景请谨慎使用
⚠️ 不同交易所的数据格式和时间戳单位不同，已统一为毫秒
⚠️ 币安有200天的时间范围限制，Gate无此限制但只能按limit取最近数据
⚠️ 资金费率为负数时，空方支付给多方（做空成本）
⚠️ 频繁调用可能触发API限流，建议合理设置查询频率

exchange.GetFundingHistory()

语法

参数

返回值

支持的交易所

示例

1. 获取最近的资金费率历史

2. 获取指定时间范围的资金费率

3. 计算平均资金费率

4. 跨交易所资金费率对比

5. 检测套利机会

6. 趋势分析

7. 计算持仓成本

数据格式差异

币安（Binance）

Gate.io

错误处理

常见问题

1. 为什么Gate的MarkPrice为0？

2. 如何理解资金费率的正负？

3. 资金费率多久结算一次？

4. 如何计算资金费用？

相关方法

应用场景

注意事项

On this page