alpaca

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Alpaca

Tools for trading on Alpaca against the Trading API: place and manage stock, crypto, and options orders; read account balances, positions, portfolio history, and activities; look up assets, market hours, and option contracts; and read watchlists. 25 scripts across account, orders, positions, assets, options, and watchlists. Trades run against Alpaca's paper (simulated) environment by default; live real-money trading requires an explicit opt-in (see Auth). Money and quantity values are returned as strings to preserve decimal precision — never coerce them to numbers. Order placement is async-confirmed:

placeOrder

acknowledges receipt with a status that can change server-side, so re-query

getOrder

before asserting a fill.

Independent, unofficial connector for Alpaca. Not affiliated with, endorsed by, or sponsored by Alpaca. "Alpaca" is a trademark of its owner, used only to identify the service this connector works with.

基于Alpaca Trading API的交易工具：下单及管理股票、加密货币和期权订单；查看账户余额、持仓、投资组合历史和交易活动；查询资产、市场营业时间和期权合约；以及读取观察列表。涵盖账户、订单、持仓、资产、期权和观察列表的25个脚本。默认情况下，交易在Alpaca的模拟（paper）环境中运行；实盘交易需要明确选择开通（参见认证部分）。金额和数量值以字符串形式返回，以保留小数精度——切勿将其强制转换为数字。下单采用异步确认机制：

placeOrder

仅确认接收订单，订单状态可能在服务器端发生变化，因此在确认成交前需重新调用

getOrder

查询。

本工具为Alpaca的独立非官方连接器，与Alpaca无关联、未获其认可或赞助。“Alpaca”是其所有者的商标，仅用于标识本连接器适配的服务。

When to use this

使用场景

Inspect the account — read balances and buying power, list open positions and unrealized P&L, review portfolio history and account activities (fills, dividends, fees), or check whether the market is open.
Place and manage orders — buy or sell stocks, crypto, or options (market/limit/stop/bracket/OCO/OTO/multi-leg); replace or cancel open orders; close or liquidate positions; exercise an options position.
Look things up — resolve a symbol's tradability/shortability/fractionability, list assets or option contracts, and read watchlists.

账户查询——查看账户余额、购买力，列出未平仓持仓及未实现盈亏，回顾投资组合历史和账户活动（成交、分红、手续费），或检查市场是否开市。
订单管理——买卖股票、加密货币或期权（市价/限价/止损/括号订单/OCO/OTO/多腿期权）；修改或取消未成交订单；平仓或清算持仓；行权期权持仓。
信息查询——确认标的代码的可交易性/可卖空性/可拆分性，列出资产或期权合约，以及读取观察列表。

Setup

安装配置

This is an agentskills.io skill.

If the connector has not been installed as a skill yet, install it first with

npx skills add zapier/connectors --skill alpaca

(or your harness's own skill-install mechanism), then continue here. Installing the skill copies these files, not dependencies. Before running the CLI, a local MCP server, or

zapier-sdk

auth commands, run

npm install --omit=dev

here once. Importing the published package as a dependency in your own project instead? That

npm install

already resolves everything — see

references/use-as-sdk.md

The connector runs on Node.js 22.18+. Pick the reference that matches how you're running it, and load it before doing anything else:

You have...	Load
An MCP-aware client — tools may already be loaded (e.g. `mcp__alpaca__<tool>` ), or you can register a local server yourself (or guide the user to)	`references/use-as-mcp.md`
Terminal / subprocess access (you can run `node` )	`references/use-as-cli.md`
Only your own code, importing this package as a dependency	`references/use-as-sdk.md`
No tool access, no terminal, no ability to import this package — you write your own code that calls the Alpaca API directly (e.g. a code-execution sandbox)	`references/use-as-recipe.md`

这是一款agentskills.io工具。

如果尚未将该连接器作为工具安装，请先执行

npx skills add zapier/connectors --skill alpaca

进行安装（或使用您的工具管理机制），然后继续后续步骤。安装工具仅复制这些文件，不包含依赖项。运行CLI、本地MCP服务器或

zapier-sdk

认证命令前，请在此目录执行一次

npm install --omit=dev

。若您的项目是通过导入已发布包作为依赖项，则

npm install

已解决所有依赖问题——详见

references/use-as-sdk.md

。

该连接器运行于**Node.js 22.18+**环境。请根据您的运行方式选择对应的参考文档，并在操作前加载：

运行环境	参考文档
支持MCP的客户端——工具可能已加载（例如 `mcp__alpaca__<tool>` ），您也可以自行注册本地服务器（或引导用户注册）	`references/use-as-mcp.md`
可访问终端/子进程（能运行 `node` 命令）	`references/use-as-cli.md`
仅使用自有代码，通过导入包作为依赖项	`references/use-as-sdk.md`
无工具访问权限、无终端、无法导入包——需自行编写调用Alpaca API的代码（例如代码执行沙箱）	`references/use-as-recipe.md`

Scripts

脚本列表

All scripts use the single connection

alpaca

. Trading tools hit the paper host by default (live requires an opt-in — see Auth).

Script	Script name	Connections	Description
`scripts/getAccount.ts`	`getAccount`	`alpaca`	Get account balances, buying power, equity, and trading-permission flags.
`scripts/getAccountConfigurations.ts`	`getAccountConfigurations`	`alpaca`	Get the account's trading configuration flags.
`scripts/getPortfolioHistory.ts`	`getPortfolioHistory`	`alpaca`	Get the account's equity and P&L time series over a period.
`scripts/listAccountActivities.ts`	`listAccountActivities`	`alpaca`	List account activities — fills, dividends, fees, transfers — by type and date.
`scripts/placeOrder.ts`	`placeOrder`	`alpaca`	Place an order to buy or sell a stock, crypto pair, or option.
`scripts/replaceOrder.ts`	`replaceOrder`	`alpaca`	Replace (modify) an open order's quantity, price, or time-in-force.
`scripts/cancelOrder.ts`	`cancelOrder`	`alpaca`	Cancel one open order by id.
`scripts/cancelAllOrders.ts`	`cancelAllOrders`	`alpaca`	Attempt to cancel every open order (per-order status list).
`scripts/listOrders.ts`	`listOrders`	`alpaca`	List orders, filtered by status, symbols, or side.
`scripts/getOrder.ts`	`getOrder`	`alpaca`	Get one order by id, including status and fill details.
`scripts/getOrderByClientOrderId.ts`	`getOrderByClientOrderId`	`alpaca`	Get one order by the client_order_id you assigned.
`scripts/listPositions.ts`	`listPositions`	`alpaca`	List all open positions with market value, cost basis, and P&L.
`scripts/getPosition.ts`	`getPosition`	`alpaca`	Get one open position by symbol or asset id.
`scripts/closePosition.ts`	`closePosition`	`alpaca`	Close (liquidate) one position, fully or partially.
`scripts/closeAllPositions.ts`	`closeAllPositions`	`alpaca`	Liquidate every open position (optionally cancel open orders first).
`scripts/exerciseOptionsPosition.ts`	`exerciseOptionsPosition`	`alpaca`	Exercise a held options position by option symbol or contract id.
`scripts/listAssets.ts`	`listAssets`	`alpaca`	List tradable assets, filtered by class, status, or exchange.
`scripts/getAsset.ts`	`getAsset`	`alpaca`	Get one asset by symbol, asset id, or CUSIP (tradability flags).
`scripts/getClock.ts`	`getClock`	`alpaca`	Get the market clock — is it open now, and the next open/close.
`scripts/getMarketCalendar.ts`	`getMarketCalendar`	`alpaca`	Get market trading days with open/close times over a date range.
`scripts/listOptionContracts.ts`	`listOptionContracts`	`alpaca`	List option contracts for underlyings, filtered by expiration/type/strike.
`scripts/getOptionContract.ts`	`getOptionContract`	`alpaca`	Get one option contract by OCC symbol or contract id.
`scripts/listWatchlists.ts`	`listWatchlists`	`alpaca`	List the account's watchlists.
`scripts/getWatchlist.ts`	`getWatchlist`	`alpaca`	Get one watchlist by id, including its asset symbols.
`scripts/getWatchlistByName.ts`	`getWatchlistByName`	`alpaca`	Get one watchlist by name, including its asset symbols.

所有脚本均使用单一连接

alpaca

。交易工具默认访问模拟环境（实盘交易需选择开通——参见认证部分）。

脚本	脚本名称	连接配置	描述
`scripts/getAccount.ts`	`getAccount`	`alpaca`	获取账户余额、购买力、权益和交易权限标识。
`scripts/getAccountConfigurations.ts`	`getAccountConfigurations`	`alpaca`	获取账户的交易配置标识。
`scripts/getPortfolioHistory.ts`	`getPortfolioHistory`	`alpaca`	获取账户在一段时间内的权益和盈亏时间序列。
`scripts/listAccountActivities.ts`	`listAccountActivities`	`alpaca`	按类型和日期列出账户活动——成交、分红、手续费、转账等。
`scripts/placeOrder.ts`	`placeOrder`	`alpaca`	下单买卖股票、加密货币对或期权。
`scripts/replaceOrder.ts`	`replaceOrder`	`alpaca`	修改未成交订单的数量、价格或有效期限。
`scripts/cancelOrder.ts`	`cancelOrder`	`alpaca`	根据ID取消单个未成交订单。
`scripts/cancelAllOrders.ts`	`cancelAllOrders`	`alpaca`	尝试取消所有未成交订单（返回每个订单的状态列表）。
`scripts/listOrders.ts`	`listOrders`	`alpaca`	按状态、标的代码或买卖方向筛选订单列表。
`scripts/getOrder.ts`	`getOrder`	`alpaca`	根据ID获取单个订单，包括状态和成交详情。
`scripts/getOrderByClientOrderId.ts`	`getOrderByClientOrderId`	`alpaca`	根据您分配的client_order_id获取单个订单。
`scripts/listPositions.ts`	`listPositions`	`alpaca`	列出所有未平仓持仓，包含市值、成本基准和盈亏。
`scripts/getPosition.ts`	`getPosition`	`alpaca`	根据标的代码或资产ID获取单个未平仓持仓。
`scripts/closePosition.ts`	`closePosition`	`alpaca`	平仓（清算）单个持仓，可全部或部分平仓。
`scripts/closeAllPositions.ts`	`closeAllPositions`	`alpaca`	清算所有未平仓持仓（可选择先取消未成交订单）。
`scripts/exerciseOptionsPosition.ts`	`exerciseOptionsPosition`	`alpaca`	根据期权代码或合约ID行权持有的期权持仓。
`scripts/listAssets.ts`	`listAssets`	`alpaca`	按类别、状态或交易所筛选可交易资产列表。
`scripts/getAsset.ts`	`getAsset`	`alpaca`	根据标的代码、资产ID或CUSIP获取单个资产（包含可交易标识）。
`scripts/getClock.ts`	`getClock`	`alpaca`	获取市场时钟——当前是否开市，以及下一次开市/闭市时间。
`scripts/getMarketCalendar.ts`	`getMarketCalendar`	`alpaca`	获取一段时间内的市场交易日及开市/闭市时间。
`scripts/listOptionContracts.ts`	`listOptionContracts`	`alpaca`	按到期日/类型/行权价筛选标的资产的期权合约列表。
`scripts/getOptionContract.ts`	`getOptionContract`	`alpaca`	根据OCC代码或合约ID获取单个期权合约。
`scripts/listWatchlists.ts`	`listWatchlists`	`alpaca`	列出账户的观察列表。
`scripts/getWatchlist.ts`	`getWatchlist`	`alpaca`	根据ID获取单个观察列表，包含其资产标的代码。
`scripts/getWatchlistByName.ts`	`getWatchlistByName`	`alpaca`	根据名称获取单个观察列表，包含其资产标的代码。

Disambiguation & refusals

歧义处理与拒绝规则

Disambiguation before a write. Trade and position tools key on an exact symbol or id, not a company name. Before acting on something the user named loosely:

Symbols / assets — if the user gives a company name ("Apple") rather than a ticker, resolve it first with
```
getAsset
```
or
```
listAssets
```
. If exactly one asset matches, act on it; if several plausibly match, list them (symbol + name + exchange) and ask which. Never guess a ticker.
Watchlists — resolve by name with
```
getWatchlistByName
```
or
```
listWatchlists
```
. Names are unique per account, so one exact (case-insensitive) match is the answer — act on it, don't over-ask. If nothing matches, say so. This connector reads watchlists but does not create or modify them (see Unsupported operations).
Orders / positions — take an
```
order_id
```
or
```
symbol
```
the user already has (from
```
listOrders
```
/
```
listPositions
```
). If they describe an order vaguely ("cancel my Tesla order"), list the candidates first and confirm before canceling.

Unsupported operations — say so and stop; don't fake it with another tool. This connector deliberately does not:

Move money — no deposits, withdrawals, transfers, bank links, or funding. Those live on Alpaca's Broker API and are out of scope.
Read market data — quotes, bars, snapshots, news, corporate actions, and option chains are out of scope. This connector wraps Alpaca's Trading API only, not the Market Data API (
```
data.alpaca.markets
```
); there are no price/history or streaming tools.
Create or modify watchlists, or change account configuration — this connector reads watchlists (
```
listWatchlists
```
/
```
getWatchlist
```
/
```
getWatchlistByName
```
) and account settings (
```
getAccountConfigurations
```
) but does not create, update, or delete them.
Trade against a live account by default — trading is paper (simulated) unless the user has explicitly enabled live (see Auth). If asked to trade real money, confirm live is enabled rather than assuming.
Manage the stock screener, OAuth apps, or account documents — not exposed.

If asked for any of these, tell the user it's unsupported and stop — don't substitute an unrelated tool and report success for an action you didn't perform.

写入操作前的歧义处理。交易和持仓工具依赖精确的标的代码或ID，而非公司名称。当用户给出模糊名称时：

标的代码/资产——若用户给出公司名称（如“Apple”）而非代码，需先通过
```
getAsset
```
或
```
listAssets
```
解析。若仅匹配到一个资产，则直接操作；若匹配到多个可能资产，则列出它们（代码+名称+交易所）并询问用户选择。切勿猜测标的代码。
观察列表——通过
```
getWatchlistByName
```
或
```
listWatchlists
```
按名称解析。每个账户的名称是唯一的，不区分大小写，匹配到一个结果即可直接操作，无需额外询问。若无匹配结果，告知用户即可。本连接器仅读取观察列表（参见不支持的操作），不支持创建或修改。
订单/持仓——使用用户已获取的
```
order_id
```
或
```
symbol
```
（来自
```
listOrders
```
/
```
listPositions
```
）。若用户模糊描述订单（如“取消我的特斯拉订单”），需先列出候选订单并确认后再取消。

**不支持的操作——直接告知用户并终止操作；切勿用其他工具替代。**本连接器明确不支持以下操作：

资金转移——不支持存款、取款、转账、银行链接或资金存入。这些属于Alpaca的Broker API范畴，不在本工具范围内。
市场数据读取——报价、K线、快照、新闻、公司行动和期权链均不在范围内。本连接器仅封装Alpaca的Trading API，不包含Market Data API（
```
data.alpaca.markets
```
）；无价格/历史或流数据工具。
创建或修改观察列表、更改账户配置——本连接器仅读取观察列表（
```
listWatchlists
```
/
```
getWatchlist
```
/
```
getWatchlistByName
```
）和账户设置（
```
getAccountConfigurations
```
），不支持创建、更新或删除。
默认实盘交易——默认使用模拟交易，实盘交易需用户明确开通（参见认证部分）。若用户要求实盘交易，需确认已开通实盘权限，切勿默认假设。
股票筛选器、OAuth应用或账户文档管理——未开放此类功能。

若用户请求上述操作，告知用户不支持并终止操作——切勿用无关工具替代并虚假报告操作成功。

Auth

认证

Every shape passes auth as one connection selector, not the secret — a

[<resolver>:]<value>

string. Every connector accepts

zapier:<connection-id>

(Zapier-managed auth — routes through Zapier's auth, retries, and governance layer); some also accept one or more direct-token resolvers (naming and count vary per connector) — check this connector's own resolvers rather than assuming. The

<resolver>:

prefix is optional; a bare value goes to the first resolver that claims it — a UUID-shaped bare value always claims

zapier:

. Each script declares the connections it needs and the resolvers each accepts. The exact syntax for passing a connection (and how to see this connector's resolver list) differs by shape — see the reference you loaded above.

Checking what's already configured first? Don't dump environment values to do it —

env

env | grep <name>

prints the value along with the name, leaking a live credential into the transcript if one is set. Check names only (

env | cut -d= -f1 | grep -i <name>

) or test a known name directly (

[ -n "$VAR_NAME" ]

Zapier-managed auth (

zapier:<connection-id>

) is experimental for Alpaca — the direct resolver (

alpaca:<PREFIX>

) is the verified path.

No connection yet? Pick one — and follow the reference's own flow to obtain it; never just ask the user for a connection id or token as if they already have one memorized:

	Load
Pass the credential directly	`references/use-without-zapier.md`
Route it through a Zapier connection	`references/use-with-zapier.md`

所有操作均通过一个连接选择器传递认证信息，而非密钥——格式为

[<resolver>:]<value>

字符串。每个连接器均接受

zapier:<connection-id>

（Zapier托管的认证——通过Zapier的认证、重试和治理层路由）；部分连接器还支持一种或多种直接令牌解析器（命名和数量因连接器而异）——请查看本连接器的解析器列表，切勿假设。

<resolver>:

前缀为可选；无前缀的值将匹配第一个可处理的解析器——UUID格式的值默认匹配

zapier:

。每个脚本都会声明所需的连接及支持的解析器。传递连接的具体语法（以及查看本连接器解析器列表的方式）因运行环境而异——请查看您加载的参考文档。

想要检查已配置的内容？切勿直接打印环境变量——

env

或

env | grep <name>

会同时打印名称和值，若包含实盘凭证则会泄露。仅检查名称（

env | cut -d= -f1 | grep -i <name>

）或直接测试已知名称（

[ -n "$VAR_NAME" ]

）。

Zapier托管的认证（

zapier:<connection-id>

）针对Alpaca仍处于实验阶段——直接解析器（

alpaca:<PREFIX>

）为已验证的方式。

尚未配置连接？请选择一种方式，并按照参考文档的流程获取连接——切勿直接向用户索要连接ID或令牌，假设他们已记住这些信息：

方式	参考文档
直接传递凭证	`references/use-without-zapier.md`
通过Zapier连接路由	`references/use-with-zapier.md`

Output format

输出格式

Every script returns a

{ data, meta }

envelope:

data
— the script's result (the shape its
```
outputSchema
```
declares; see the reference you loaded above for how to inspect a script's exact schema in your shape).
meta.outputDataValidation
— what validating
```
data
```
did:
- ```
{ skipped: false, droppedPaths: null }
```
  — validated, nothing removed.
- ```
{ skipped: false, droppedPaths: [...], instruction }
```
  — validated, but those paths were stripped from
```
data
```
  : fields the script returned from the API that the
```
outputSchema
```
  doesn't declare. If you need them, re-run with output validation skipped.
- ```
{ skipped: true }
```
  — validation was bypassed;
```
data
```
  is the raw, unchecked script output.

Reading dropped fields /
skipOutputDataValidation
. To receive the raw, unvalidated result, opt out of output validation (the exact syntax differs by shape — see the reference you loaded above). Input validation is never skipped.

Trimming the result /
filterOutputData
. To shrink a large result down to the fields you need, pass a jq expression that post-processes

data

(again, exact syntax per shape). The jq runs against

data

only, NOT the

{ data, meta }

envelope, so write it rooted at

data

(run the script's

--help

— or your shape's equivalent — to see its output schema). The transformed value replaces

data

meta

is preserved, and the result is NOT re-validated against the output schema.

每个脚本均返回

{ data, meta }

格式的结果：

data
——脚本的执行结果（符合其
```
outputSchema
```
定义的结构；请查看您加载的参考文档，了解如何在您的环境中查看脚本的精确输出 schema）。
meta.outputDataValidation
——对
```
data
```
的验证结果：
- ```
{ skipped: false, droppedPaths: null }
```
  ——已验证，无内容移除。
- ```
{ skipped: false, droppedPaths: [...], instruction }
```
  ——已验证，但
```
data
```
  中的部分路径被移除：脚本从API返回的字段未在
```
outputSchema
```
  中声明。若需要这些字段，请跳过输出验证重新运行。
- ```
{ skipped: true }
```
  ——已跳过验证；
```
data
```
  为脚本的原始未校验输出。

读取被移除的字段 /
skipOutputDataValidation
。若要接收原始未校验结果，请选择跳过输出验证（具体语法因运行环境而异——请查看您加载的参考文档）。输入验证无法跳过。

结果精简 /
filterOutputData
。若要精简大型结果至所需字段，请传入一个jq表达式对

data

进行后处理（语法因运行环境而异）。jq仅针对

data

运行，而非

{ data, meta }

整体，因此表达式需以

data

为根（运行脚本的

--help

或您环境中的等效命令查看输出schema）。转换后的值将替换

data

，

meta

保留不变，且结果不会重新校验输出schema。

References

参考文档

Load the matching reference file before working in that area:

Reference	Covers	Load it when
`references/alpaca-api-gotchas.md`	Alpaca API behavior the schemas don't capture: auth & paper/live hosts, the `{code, message}` error envelope + status codes, rate limits, pagination, order types/TIF/classes (bracket/oco/oto/mleg), fractional/notional & extended-hours rules, order lifecycle & cancel/replace, position close/liquidate/exercise, and account/watchlist/calendar details	Load before placing, replacing, or canceling orders; closing or exercising positions; or whenever a call returns an unexpected HTTP status or error code

在对应场景工作前，请加载匹配的参考文档：

参考文档	涵盖内容	加载时机
`references/alpaca-api-gotchas.md`	Alpaca API的特殊行为（未在schema中体现）：认证与模拟/实盘环境、 `{code, message}` 错误格式+状态码、速率限制、分页、订单类型/有效期限/类别（括号订单/OCO/OTO/多腿期权）、 fractional/notional及盘后交易规则、订单生命周期与取消/修改、持仓平仓/清算/行权，以及账户/观察列表/日历详情	在下单、修改或取消订单；平仓或行权持仓；或调用返回意外HTTP状态码或错误信息时加载