美股时段

Alpaca API 入门教程:申请 API Key、Paper Trading 模拟盘、Python alpaca-py 查行情和下单(2026)

2026-11-15 更新

Alpaca 的 API 可以用代码查美股行情、下单、管理持仓。入门只要三步:用邮箱注册,打开 Paper Trading 模拟账户(默认 10 万美元虚拟资金),在后台生成 API Key,再用官方 Python SDK alpaca-py 写十几行代码。股票、ETF 和个股期权零售交易不收佣金,免费行情只有 IEX 一家交易所的数据,全市场 SIP 行情每月 99 美元。实盘开户步骤见Alpaca 开户教程,本文只讲 API。

Alpaca API 由哪几部分组成

接口用途地址
Trading API(实盘)账户、下单、持仓、期权合约api.alpaca.markets
Trading API(模拟盘)同上,用虚拟资金paper-api.alpaca.markets
Market Data API股票、期权、加密货币行情和新闻,实盘和模拟盘共用data.alpaca.markets
Broker API给券商和金融 App 开户用,个人用不到本文不涉及

用 alpaca-py 时不用手写这些地址,SDK 按参数自动选择。

第一步:注册并打开 Paper Trading

在 Alpaca 官网用邮箱注册,任何国家的人都能开 Paper Only 账户。注册后默认就是模拟盘,有 10 万美元虚拟资金。资金额创建后不能改,想重来就在账户菜单里新建一个模拟账户。

模拟盘和实盘有几处差别,回测结果要打折看:

  • 不模拟股息。
  • 不模拟市场冲击、网络延迟造成的滑点、限价单排队位置和监管费。
  • 只要价格可成交就按全部数量成交,不检查盘口深度,大单成交会比实盘顺利。
  • Paper Only 账户只给 IEX 行情。

想转实盘,要完成实名开户并入金。Alpaca 官网说非美国居民最低 1 美元即可入金,但是否接受你所在国家的居民,以开户页面为准。入金方式和外汇规定见美股券商入金和出金指南。

第二步:生成 API Key

  1. 登录后台,确认顶部切换到 Paper Trading。
  2. 在页面右侧找到 API Keys,点 Generate New Key。
  3. 页面显示 Key ID 和 Secret Key。Secret Key 只显示这一次,马上保存。
  4. 丢了 Secret Key 只能点 Regenerate 重新生成,旧的一对 Key 会立刻失效。

模拟盘和实盘的 Key 互不通用,用实盘 Key 连模拟盘地址会报认证错误。Key 能直接下单,不要写进代码,也不要传到 GitHub。用环境变量保存:

# macOS / Linux
export ALPACA_API_KEY="你的 Key ID"
export ALPACA_SECRET_KEY="你的 Secret Key"

# Windows PowerShell
$env:ALPACA_API_KEY="你的 Key ID"
$env:ALPACA_SECRET_KEY="你的 Secret Key"

第三步:安装 alpaca-py

pip install alpaca-py

alpaca-py 是 Alpaca 官方的 Python SDK,2026 年 11 月 5 日发布的 0.45.0 版要求 Python 3.10 以上,GitHub 主分支已经改成 3.11 以上,建议直接用 Python 3.11 或更新版本。安装时会一起装上 pandas。旧库 alpaca-trade-api 已在 2026 年 6 月归档,网上用它写的老教程不要再照抄。

第四步:连接账户

import os
from alpaca.trading.client import TradingClient

API_KEY = os.environ["ALPACA_API_KEY"]
SECRET_KEY = os.environ["ALPACA_SECRET_KEY"]

# paper=True 连模拟盘;换成实盘 key 后改成 paper=False
trading = TradingClient(API_KEY, SECRET_KEY, paper=True)

account = trading.get_account()
print(account.status, account.cash, account.buying_power)

clock = trading.get_clock()
print("现在开盘吗:", clock.is_open)

TradingClient 的 paper 参数决定连哪个环境。能打印出账户状态和现金,说明 Key 和网络都没问题。

第五步:查行情

from datetime import datetime, timedelta
from alpaca.data.historical import StockHistoricalDataClient
from alpaca.data.requests import StockLatestQuoteRequest, StockBarsRequest
from alpaca.data.timeframe import TimeFrame
from alpaca.data.enums import DataFeed

data = StockHistoricalDataClient(API_KEY, SECRET_KEY)

# 最新报价(免费账户用 IEX)
quote = data.get_stock_latest_quote(
    StockLatestQuoteRequest(symbol_or_symbols="AAPL", feed=DataFeed.IEX)
)
print(quote["AAPL"].bid_price, quote["AAPL"].ask_price)

# 最近 30 天日线
bars = data.get_stock_bars(
    StockBarsRequest(
        symbol_or_symbols="AAPL",
        timeframe=TimeFrame.Day,
        start=datetime.now() - timedelta(days=30),
        feed=DataFeed.IEX,
    )
)
print(bars.df.tail())

返回结果按股票代码取值,查一只股票也要写 quote["AAPL"]。.df 把 K 线转成 pandas DataFrame。symbol_or_symbols 可以传列表,一次查多只股票,省请求次数。免费账户建议显式写 feed=DataFeed.IEX,原因见后面的行情订阅一节。

第六步:下单

from alpaca.trading.requests import MarketOrderRequest, LimitOrderRequest
from alpaca.trading.enums import OrderSide, TimeInForce

# 市价买 1 股
order = trading.submit_order(
    MarketOrderRequest(
        symbol="AAPL",
        qty=1,
        side=OrderSide.BUY,
        time_in_force=TimeInForce.DAY,
    )
)
print(order.id, order.status)

# 限价买 1 股,再撤单
limit = trading.submit_order(
    LimitOrderRequest(
        symbol="AAPL",
        qty=1,
        side=OrderSide.BUY,
        time_in_force=TimeInForce.DAY,
        limit_price=150,
    )
)
trading.cancel_order_by_id(limit.id)

print(trading.get_all_positions())
  • TimeInForce.DAY 是当日有效,收盘没成交自动取消。
  • 美东 16:00 以后提交、不能在盘后交易的订单(包括市价单),会排到下一个交易日开盘再发出。交易时段见美股交易时间和休市日历。
  • 盘前盘后下单要满足三个条件:限价单、extended_hours=True、有效期为 DAY 或 GTC。
  • 碎股订单只能用 DAY 有效期。

Alpaca 支持期权吗

支持。Alpaca 的期权权限分 4 级:

等级能做什么
Level 0关闭期权交易
Level 1Covered Call、Cash-Secured Put
Level 2Level 1 加上买入看涨、看跌
Level 3Level 1、2 加上看涨价差、看跌价差

模拟盘默认开通期权,可以在 Account → Configure 里关掉。实盘要另外申请权限,审核比开户复杂。各级别的含义和其他券商的对比见美股期权交易权限等级。

期权订单的规则:

  • 订单类型支持市价、限价、止损、止损限价;止损和止损限价只能用于单腿订单。多腿价差在 SDK 里用 OrderClass.MLEG 加 OptionLegRequest。
  • 有效期只能用 DAY 或 GTC。数量必须是整数,不能按金额下单,不能盘前盘后交易。
  • 到期时价内至少 0.01 美元的合约会自动行权。账户购买力不够行权时,Alpaca 会在到期前一小时内替你平仓。
  • 被指派不会通过 WebSocket 推送,要用 REST 接口查询;模拟盘的指派记录第二天才出现。

下面的例子先查合约,再用合约代码下单。合约代码格式是 OCC 标准,例如 AAPL261218C00250000 表示 AAPL、2026 年 12 月 18 日到期、行权价 250 美元的看涨期权。期权基础概念见看涨期权与看跌期权的基本概念。

from datetime import date, timedelta
from alpaca.trading.requests import GetOptionContractsRequest, LimitOrderRequest
from alpaca.trading.enums import ContractType, OrderSide, TimeInForce

# 查 AAPL 未来 7 到 45 天到期的看涨合约
resp = trading.get_option_contracts(
    GetOptionContractsRequest(
        underlying_symbols=["AAPL"],
        type=ContractType.CALL,
        expiration_date_gte=date.today() + timedelta(days=7),
        expiration_date_lte=date.today() + timedelta(days=45),
        limit=10,
    )
)
for c in resp.option_contracts:
    print(c.symbol, c.strike_price, c.expiration_date)

# 用合约代码下限价单:买 1 张,每股 1.00 美元,1 张 = 100 股,最多花 100 美元
contract = resp.option_contracts[0]
opt_order = trading.submit_order(
    LimitOrderRequest(
        symbol=contract.symbol,
        qty=1,
        side=OrderSide.BUY,
        time_in_force=TimeInForce.DAY,
        limit_price=1.00,
    )
)
print(opt_order.status)

例子里取的是列表第一个合约,只为演示调用方式,不代表该买这张合约。买期权最多亏掉全部权利金,卖期权的亏损可能远大于收到的权利金,先在模拟盘跑通再考虑实盘。

费用

项目费用
美股、ETF 佣金零售订单 0
个股和 ETF 期权佣金零售订单 0;一个月里平均每个交易日下 390 单以上会被认定为专业交易者,每张 0.10–0.40 美元
指数期权(SPX、VIX 等)每张 0.50 美元,另加交易所费用
SEC 交易费只在卖出时收,成交金额 × 0.0000206
FINRA CAT 费买卖都收,每股 0.000003 美元(1 张期权按 100 股算)
期权 ORF、OCC 清算费买卖都收,每张 0.015 美元和 0.025 美元
出金美国境内电汇 15 美元,国际电汇 35 美元
融资利率默认年化 6.50%

以上来自 Alpaca 2026 年 10 月 12 日修订的费用表,以官网最新版为准。

行情订阅:免费 IEX 和付费 SIP 的区别

IEX 是美国的一家股票交易所,免费账户的实时行情只来自这一家。SIP 是把全美各交易所的报价和成交汇总在一起的数据源,也就是券商软件里看到的全市场价格。成交不活跃的股票,IEX 的报价可能和全市场最优价差得比较多。

项目Basic(免费)Algo Trader Plus(每月 99 美元)
股票实时数据只有 IEX全美所有交易所(SIP)
股票历史数据不能查最近 15 分钟不限
WebSocket 订阅股票数30 只不限
历史数据接口调用每分钟 200 次每分钟 10,000 次
期权实时数据Indicative(参考价)OPRA 实时
期权 WebSocket 报价数2001,000

在 alpaca-py 里用 feed 参数选数据源:DataFeed.IEX、DataFeed.SIP、DataFeed.DELAYED_SIP(延迟 15 分钟的 SIP)。只做日线策略,免费版通常够用;做日内或期权策略,需要付费版的实时数据。

限流

  • Trading API 每个账户每分钟 200 次请求,超出返回 HTTP 429(Too Many Requests)。这个上限不能自己调高,要找 Alpaca 客服。
  • Market Data API 免费版每分钟 200 次,Algo Trader Plus 每分钟 10,000 次。
  • 减少请求的办法:一次请求查多只股票;实时数据用 WebSocket 订阅,不要循环轮询;收到 429 后等几秒再重试。

常见报错

报错常见原因处理
401 或 403 认证失败Key 抄错;用实盘 Key 连了模拟盘,或反过来检查环境变量和 paper 参数是否对应
403 购买力不足现金或可卖股数不够先用 get_account() 看 buying_power
422 参数错误期权数量写成小数、期权单加了盘后参数、价格精度不对对照上面的订单规则改参数
429 请求过多超过每分钟 200 次合并请求,等几秒再试
查行情报订阅不允许免费账户查了 SIP 数据加上 feed=DataFeed.IEX

上手要点

  • 先在模拟盘跑通,模拟盘 Key 和实盘 Key 分开保存。
  • Secret Key 只显示一次,放环境变量,不进代码仓库。
  • 用 alpaca-py,不要用已归档的 alpaca-trade-api。
  • 免费行情只有 IEX,查数据时写明 feed。
  • 期权按合约代码下单,数量是整数,1 张对应 100 股。

想找有大单异动的期权合约作为研究起点,可以看本站 App 里的期权异动提醒,安装见下载页。

常见问题

Alpaca API 要钱吗?

注册、模拟盘和 API Key 都免费,美股、ETF 和个股期权零售交易不收佣金。行情方面,免费版只有 IEX 数据,全市场 SIP 实时行情的 Algo Trader Plus 每月 99 美元。

Alpaca 模拟盘有多少钱,能重置吗?

Paper Trading 账户默认 10 万美元虚拟资金,创建后不能改金额。想重来可以在账户菜单里新建一个模拟账户,新账户要重新生成 API Key。

Alpaca Secret Key 忘了怎么办?

Secret Key 只在生成时显示一次,找不回来。只能在后台点 Regenerate 重新生成一对,旧的 Key 会立刻失效,代码里的配置要一起换。

Alpaca API 可以交易期权吗?

可以。Alpaca 期权权限分 Level 0 到 3,最高支持看涨、看跌价差;模拟盘默认开通,实盘要另外申请。期权订单数量必须是整数,不能盘前盘后交易。

Alpaca API 每分钟能调用多少次?

Trading API 每个账户每分钟 200 次,超出返回 429 错误。行情接口免费版每分钟 200 次,Algo Trader Plus 每分钟 10,000 次。

Alpaca 免费行情和付费行情有什么区别?

免费版实时行情只来自 IEX 一家交易所,WebSocket 最多订阅 30 只股票,历史数据查不到最近 15 分钟。付费版用汇总全美交易所的 SIP 数据,订阅数量不限。

返回课程

美股智投会员$99/月起,目前全部免费查看会员