ftshare 1.0.12

让金融数据成为 AI 的可靠上下文。
FTShare 面向 AI Agent、量化研究和金融应用提供统一、可验证、可扩展的金融数据服务。

FTShare 官网 · 获取 API Key · 数据接口文档 · 问题反馈

先看它能做什么

FTShare-python-sdk 是 FTShare 的 Python 数据接入层。它将基础金融数据和 FTShare 特色因子统一成 Python 调用方式，默认返回 pandas DataFrame，可以直接进入分析、研究和应用开发流程。

_{FTShare 官网。点击图片进入产品与套餐页面。}

三步跑通第一次调用

1. 获取 API Key

登录 FTShare 账号中心，获取当前账号的 API Key。

2. 安装 SDK

推荐通过 PyPI 安装（需要 Python 3.9 及以上）：

pip install ftshare

升级到最新版本：

pip install --upgrade ftshare

pandas 和 requests 等运行依赖会自动安装。如需本地开发，也可以从 GitHub 源码安装：

git clone https://github.com/FTShare-Lab/FTShare-python-sdk.git
cd FTShare-python-sdk
pip install -e .

3. 查询数据

export FTSHARE_API_KEY="your_api_key"

import ftshare as ft

market = ft.market_api()

df = market.ashare_news_sentiment_factors(
    trade_code="600519.SH",
    start_date="20260801",
    end_date="20260831",
    limit=5,
)

print(df.head())

选择适合你的 FTShare 接入方式

三种方式连接同一套 FTShare 金融数据服务。SDK 适合稳定编程，MCP 适合标准 Agent 工具调用，Skill 适合由 Agent 理解问题并选择数据接口。

为什么使用 Python SDK

• DataFrame-first： 默认返回 pandas DataFrame，减少重复的数据转换工作。
• 统一入口： 通过 ft.market_api() 创建客户端，同时接入基础金融数据与 FTShare 特色因子。
• 多种返回形态： 支持 DataFrame、Python 行数据与原始 JSON。
• 字段与分页： 支持字段筛选、分页和多页拉取。
• 明确异常： 区分 HTTP、JSON 解析和服务端业务错误。
• 可复用底座： 可用于研究脚本、数据应用、MCP 工具和 Agent 工作流的数据接入层。

常用客户端配置

import ftshare as ft

# 默认从 FTSHARE_API_KEY 环境变量读取
market = ft.market_api(timeout=20)

# 也可以显式传入
market = ft.market_api(api_key="your_api_key", timeout=20)

自定义 Base URL：

market = ft.market_api(
    base_url="https://market.ft.tech/gateway/",
    timeout=20,
)

返回类型

默认返回 DataFrame：

df = market.ashare_news_sentiment_factors(
    trade_code="600519.SH",
    limit=10,
)

返回 Python 行数据：

rows = market.ashare_news_sentiment_factors(
    trade_code="600519.SH",
    limit=10,
    as_dataframe=False,
)

返回服务端完整 JSON：

payload = market.ashare_news_sentiment_factors(
    trade_code="600519.SH",
    limit=10,
    raw=True,
)

分页与结果控制

df = market.ashare_news_sentiment_factors(
    trade_code="600519.SH",
    page=1,
    page_size=20,
)

df = market.ashare_news_sentiment_factors(
    trade_code="600519.SH",
    all_pages=True,
    max_pages=3,
)

详细的接口参数、字段与专题说明请查看 FTShare 数据接口文档。

错误处理

from ftshare import (
    FtshareAPIError,
    FtshareDecodeError,
    FtshareHTTPError,
)

• FtshareHTTPError：HTTP 状态码不是 2xx。
• FtshareDecodeError：响应不是合法 JSON。
• FtshareAPIError：服务端返回业务错误。

开发与测试

git clone https://github.com/FTShare-Lab/FTShare-python-sdk.git
cd FTShare-python-sdk
pip install -e ".[test]"
python3 -m pytest

真实接口集成测试默认跳过：

FTSHARE_RUN_INTEGRATION=1 python3 -m pytest tests/test_integration_market.py

开源代码与数据服务边界

本仓库代码采用 MIT License。开源许可证覆盖本仓库代码，不自动包含 FTShare 托管数据服务的访问额度、数据授权、再分发权或商业数据使用权；相关范围以产品页面和服务条款为准。

社区与反馈

• 使用问题与功能建议：GitHub Issues
• 正式产品与套餐：FTShare
• API Key 管理：账号中心
• MCP 接入：FTShare-MCP
• Agent Skill：FTShare-skill

加入 FTShare 社区交流群

欢迎加入 FTShare 社区交流群，讨论 Python SDK、特色因子、金融数据接口、MCP、Skill 和 Agent 使用。

群内用于交流使用经验和补充问题信息；Bug、功能需求和接口问题建议优先通过 GitHub Issues 提交，便于公开跟踪和沉淀。

如二维码失效，请在 Issues 中留言。

FTShare · 让金融数据成为 AI 的可靠上下文