> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alphafin.x-pai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

# API 参考

本章节提供了AlphaFinance API的全面技术参考。API遵循RESTful设计原则，使用标准HTTP方法进行请求，并返回JSON格式的响应。

## API基础

### 基本URL

所有API请求都使用以下基本URL：

```
https://api.alphafin.x-pai.com/v1
```

### 请求格式

API支持以下HTTP方法：

* **GET**：获取资源
* **POST**：创建资源
* **PUT**：更新资源
* **DELETE**：删除资源

### 身份验证

所有API请求都需要使用API密钥进行身份验证。您可以在请求头中包含您的API密钥：

```bash theme={null}
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/basic-info?symbol=600519" \
  -H "X-API-KEY: your_api_key_here"
```

详细的身份验证说明请参阅[身份验证](/authentication)文档。

### 响应格式

所有API响应都以JSON格式返回，并包含以下标准字段：

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    // 响应数据...
  }
}
```

* `code`：HTTP状态码，表示请求的结果
* `message`：对结果的简短描述
* `data`：包含请求的实际数据

对于出错的请求，响应包含错误详情：

```json theme={null}
{
  "code": 400,
  "message": "Bad Request: Missing required parameter 'symbol'",
  "error": "missing_parameter"
}
```

## API类别

AlphaFinance API按功能分为以下主要类别：

### 股票信息

股票基本信息相关接口，包括股票搜索、基本信息、上市状态等。

<CardGroup cols={2}>
  <Card title="股票搜索" icon="magnifying-glass" href="/api-reference/stock/search">
    搜索股票，支持按名称、代码、拼音和行业筛选。
  </Card>

  <Card title="基本信息" icon="circle-info" href="/api-reference/stock/basic-info">
    获取股票的基本信息，如名称、代码、交易所、行业分类等。
  </Card>

  <Card title="上市状态" icon="tag" href="/api-reference/stock/listing-status">
    获取股票的上市状态，包括上市日期、退市日期等信息。
  </Card>
</CardGroup>

### 行情数据

提供股票价格和交易相关的数据，包括日线数据、分钟线数据、实时行情等。

<CardGroup cols={2}>
  <Card title="日线数据" icon="calendar-day" href="/api-reference/market/daily">
    获取股票的日K线数据，包括开盘价、收盘价、最高价、最低价、交易量等。
  </Card>

  <Card title="分钟线数据" icon="clock" href="/api-reference/market/intraday">
    获取股票的分钟K线数据，支持1分钟、5分钟、15分钟等多种时间周期。
  </Card>

  <Card title="实时行情" icon="bolt" href="/api-reference/market/realtime">
    获取股票的实时行情数据，包括最新价、涨跌幅、成交量等。
  </Card>
</CardGroup>

### 财务数据

提供公司财务报表相关数据，包括利润表、资产负债表、现金流量表等。

<CardGroup cols={2}>
  <Card title="利润表" icon="chart-line" href="/api-reference/financials/income-statement">
    获取公司的利润表数据，包括营业收入、营业利润、净利润等。
  </Card>

  <Card title="资产负债表" icon="scale-balanced" href="/api-reference/financials/balance-sheet">
    获取公司的资产负债表数据，包括总资产、总负债、股东权益等。
  </Card>

  <Card title="现金流量表" icon="money-bill-transfer" href="/api-reference/financials/cash-flow">
    获取公司的现金流量表数据，包括经营活动、投资活动、筹资活动现金流等。
  </Card>
</CardGroup>

### 公司事件

提供公司公告、分红、IPO等事件数据。

<CardGroup cols={2}>
  <Card title="公司公告" icon="newspaper" href="/api-reference/events/announcements">
    获取公司公告信息，包括定期报告、临时公告等。
  </Card>

  <Card title="分红信息" icon="hand-holding-dollar" href="/api-reference/events/dividends">
    获取公司分红信息，包括股息、红股、转增股本等。
  </Card>

  <Card title="IPO信息" icon="rocket" href="/api-reference/events/ipo">
    获取公司IPO相关信息，包括发行价、发行数量、上市日期等。
  </Card>
</CardGroup>

### 行业数据

提供行业分类和行业表现相关数据。

<CardGroup cols={2}>
  <Card title="行业分类" icon="sitemap" href="/api-reference/industry/classification">
    获取行业分类信息，支持多种行业分类标准。
  </Card>

  <Card title="行业表现" icon="chart-pie" href="/api-reference/industry/performance">
    获取行业表现数据，包括行业指数、行业涨跌幅等。
  </Card>
</CardGroup>

### 指数数据

提供股票指数相关数据，包括指数列表、成分股、指数表现等。

<CardGroup cols={2}>
  <Card title="指数列表" icon="list" href="/api-reference/indices/list">
    获取股票指数列表，包括主要指数和行业指数。
  </Card>

  <Card title="指数成分" icon="puzzle-piece" href="/api-reference/indices/constituents">
    获取指数成分股信息，包括成分股列表、权重等。
  </Card>

  <Card title="指数表现" icon="chart-column" href="/api-reference/indices/performance">
    获取指数表现数据，包括指数价格、涨跌幅等。
  </Card>
</CardGroup>

## 通用参数

以下是适用于多个API端点的通用参数：

| 参数名          | 类型  | 描述                 |
| ------------ | --- | ------------------ |
| `fields`     | 字符串 | 指定返回的字段，用逗号分隔      |
| `symbol`     | 字符串 | 股票代码或指数代码          |
| `begin_date` | 字符串 | 起始日期，格式为YYYY-MM-DD |
| `end_date`   | 字符串 | 结束日期，格式为YYYY-MM-DD |
| `limit`      | 整数  | 返回结果的最大数量          |
| `page`       | 整数  | 分页参数，指定要返回的页码      |

## 错误处理

API使用标准HTTP状态码指示请求的成功或失败：

| 状态码 | 描述                      |
| --- | ----------------------- |
| 200 | 成功                      |
| 400 | 错误的请求，可能是缺少必需参数或参数格式不正确 |
| 401 | 未授权，API密钥无效             |
| 403 | 禁止访问，没有足够的权限            |
| 404 | 未找到请求的资源                |
| 429 | 请求过多，超出速率限制             |
| 500 | 服务器内部错误                 |

详细的错误码列表请参阅[错误码](/api-reference/errors)文档。

## 速率限制

为了保护服务质量，API实施了速率限制。具体限制取决于您的订阅计划。超出限制的请求将收到429状态码响应。

详细的速率限制信息请参阅[速率限制](/api-reference/rate-limits)文档。

## 版本控制

当前API版本为`v1`。我们会提前通知重大的API变更，并提供足够的时间进行迁移。

## 开始使用

选择一个API端点开始使用：

* [股票搜索](/api-reference/stock/search)
* [日线数据](/api-reference/market/daily)
* [利润表](/api-reference/financials/income-statement)

或者查看[快速入门](/quickstart)指南，了解如何开始使用API。