> ## 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.

# Quickstart

# 快速入门

通过本指南，您将学习如何开始使用AlphaFinance API获取A股市场数据。

## 前提条件

在开始之前，请确保您已经：

1. 在 [AlphaFinance控制台](https://alphafin.x-pai.com/dashboard) 创建了账户
2. 获取了API密钥

## 身份验证

所有API请求都需要通过API密钥进行身份验证。您可以通过添加 `X-API-KEY` 请求头来完成身份验证：

```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"
```

<Note>
  请妥善保管您的API密钥，不要在客户端代码或公开仓库中暴露它。
</Note>

## 基本请求结构

AlphaFinance API采用RESTful设计，基本URL结构为：

```
https://api.alphafin.x-pai.com/v1/{资源类别}/{具体资源}
```

例如：

* `https://api.alphafin.x-pai.com/v1/stock/search` - 搜索股票
* `https://api.alphafin.x-pai.com/v1/market/daily` - 获取日K行情数据
* `https://api.alphafin.x-pai.com/v1/financials/income-statement` - 获取利润表数据

## 常见参数

以下是API请求中常用的查询参数：

* `symbol` - 股票代码，如 `600519`（贵州茅台）
* `fields` - 指定返回字段，用逗号分隔
* `begin_date` / `end_date` - 指定日期范围，格式为 `YYYY-MM-DD`
* `limit` - 限制返回结果数量
* `page` - 分页参数，用于获取更多结果

## 示例：获取股票基本信息

以下示例展示如何获取贵州茅台(600519)的基本信息：

<CodeGroup>
  ```bash cURL 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"
  ```

  ```python Python theme={null}
  import requests

  api_key = "your_api_key_here"
  url = "https://api.alphafin.x-pai.com/v1/stock/basic-info"

  params = {
      "symbol": "600519"
  }

  headers = {
      "X-API-KEY": api_key
  }

  response = requests.get(url, params=params, headers=headers)
  data = response.json()

  print(data)
  ```

  ```javascript JavaScript theme={null}
  const apiKey = 'your_api_key_here';
  const url = 'https://api.alphafin.x-pai.com/v1/stock/basic-info?symbol=600519';

  fetch(url, {
    method: 'GET',
    headers: {
      'X-API-KEY': apiKey
    }
  })
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class FinDataExample {
      public static void main(String[] args) {
          String apiKey = "your_api_key_here";
          String url = "https://api.alphafin.x-pai.com/v1/stock/basic-info?symbol=600519";
          
          HttpClient client = HttpClient.newHttpClient();
          HttpRequest request = HttpRequest.newBuilder()
                  .uri(URI.create(url))
                  .header("X-API-KEY", apiKey)
                  .GET()
                  .build();
          
          client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
                  .thenApply(HttpResponse::body)
                  .thenAccept(System.out::println)
                  .join();
      }
  }
  ```
</CodeGroup>

响应示例：

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "symbol": "600519",
    "name": "贵州茅台",
    "exchange": "SSE",
    "industry": "食品饮料",
    "listing_date": "2001-08-27",
    "description": "贵州茅台酒股份有限公司是中国贵州省仁怀市茅台镇生产和销售茅台酒的上市公司。",
    "website": "http://www.moutaichina.com/",
    "market_cap": 2187650000000,
    "issued_shares": 1256197800,
    "par_value": 1.0,
    "status": "上市"
  }
}
```

## 示例：获取股票历史行情

以下示例展示如何获取贵州茅台(600519)在2023年1月的历史行情数据：

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.alphafin.x-pai.com/v1/market/daily?symbol=600519&begin_date=2023-01-01&end_date=2023-01-31" \
    -H "X-API-KEY: your_api_key_here"
  ```

  ```python Python theme={null}
  import requests

  api_key = "your_api_key_here"
  url = "https://api.alphafin.x-pai.com/v1/market/daily"

  params = {
      "symbol": "600519",
      "begin_date": "2023-01-01",
      "end_date": "2023-01-31"
  }

  headers = {
      "X-API-KEY": api_key
  }

  response = requests.get(url, params=params, headers=headers)
  data = response.json()

  print(data)
  ```
</CodeGroup>

响应示例（部分数据）：

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "symbol": "600519",
    "name": "贵州茅台",
    "daily": [
      {
        "date": "2023-01-03",
        "open": 1675.0,
        "high": 1688.0,
        "low": 1659.0,
        "close": 1679.0,
        "volume": 2514100,
        "amount": 4218762600.0,
        "change": 26.0,
        "pct_change": 1.57,
        "turnover": 0.2
      },
      {
        "date": "2023-01-04",
        "open": 1683.0,
        "high": 1707.11,
        "low": 1673.0,
        "close": 1702.0,
        "volume": 3419300,
        "amount": 5792633200.0,
        "change": 23.0,
        "pct_change": 1.37,
        "turnover": 0.27
      },
      // 更多日期的数据...
    ]
  }
}
```

## 错误处理

API在出现错误时会返回相应的HTTP状态码和JSON格式的错误信息：

```json theme={null}
{
  "code": 401,
  "message": "Unauthorized: Invalid API key",
  "error": "invalid_key"
}
```

常见错误码：

| 状态码 | 描述               |
| --- | ---------------- |
| 400 | 请求参数错误           |
| 401 | 未授权（API密钥无效）     |
| 403 | 请求被禁止（超出限制或权限不足） |
| 404 | 资源不存在            |
| 429 | 请求过于频繁（超出速率限制）   |
| 500 | 服务器内部错误          |

## 分页

对于可能返回大量数据的端点，我们提供分页功能：

```bash theme={null}
curl -X GET "https://api.alphafin.x-pai.com/v1/stock/search?keyword=银行&limit=10&page=2" \
  -H "X-API-KEY: your_api_key_here"
```

分页参数：

* `limit` - 每页返回的结果数量（默认：20，最大：100）
* `page` - 页码，从1开始（默认：1）

响应中会包含分页信息：

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": [...],
  "pagination": {
    "current_page": 2,
    "total_pages": 5,
    "total_items": 48,
    "items_per_page": 10
  }
}
```

## 后续步骤

现在您已经了解了如何使用AlphaFinance API，您可以：

1. 查看 [API参考文档](/api-reference/introduction) 了解所有可用的端点
2. 学习如何使用 [股票代码体系](/core-concepts/stock-codes) 和 [数据频率](/core-concepts/data-frequency)
3. 探索我们的 [SDK和工具](/sdk) 简化开发过程

如果您有任何问题，请随时 [联系我们](mailto:support@alphafin.x-pai.com) 或访问我们的 [开发者社区](https://discord.gg/findatahub)。