Broker API 入门
机器翻译译自英文（docs.alpaca.markets）本页 57 段已全部译完
沙盒环境作为一个并行环境，你可以在其中安全地测试我们的 API，而不会向市场发送任何真实交易。所有价格和执行时间（即市场时段）在沙盒和生产环境中都保持一致。
你可以按照以下步骤在 broker 仪表盘中测试特定调用，或访问 Postman 集合，在一个地方查看和测试所有可能的请求。
Postman 集合
要开始使用 Broker API Postman 集合，你可以访问 Postman 上的 Alpaca 工作区分叉该集合，或将下方文件直接导入到你自己的工作区。
在 Postman 上分叉 Broker API 集合
请参阅此教程了解如何分叉集合和示例环境，并立即开始调用。我们建议遵循此方法，以便你的集合与我们对 API 所做的更改保持同步。
导入 Broker API 集合
- 下载 Broker API API 集合
- 将文件导入 Postman（File -> Import..）
- 使用以下变量创建 Postman 环境。请务必像下图所示在右上角选择该环境。
- 在选中已创建的环境时，发送定义的 HTTP 请求之一。
在 Broker 仪表盘（Brokerdash）上测试
0. 在 Brokerdash 上设置 Broker API
API 密钥
当你在 Alpaca 注册账户时，你将收到 API_KEY 和 API_SECRET，请务必将它们保存在安全的地方。
Broker API 必须使用 HTTP Basic 认证。使用你的代理机构 API_KEY 和 API_SECRET 作为用户名和密码。格式为 key:secret。用 base-64 编码该字符串，然后将其作为认证头发送。
实盘环境
我们在仪表盘中提供了一个 API 工具，使用你的 API 密钥凭证直接从浏览器发送请求并接收响应。
只需导航到 API/Devs > Live Testing 并试用我们的 API。
发出你的第一个请求
此时我们可以假设你尚未创建任何账户，但你可以进行的首批 API 调用之一是 GET /v1/assets，它不需要请求体，并会返回 Alpaca 上可用的所有资产。
响应将包含一个资产数组，截至 2021-05-17，第一个是 Agilent Technologies Inc.
{
"id": "7595a8d2-68a6-46d7-910c-6b1958491f5c",
"class": "us_equity",
"exchange": "NYSE",
"symbol": "A",
"name": "Agilent Technologies Inc.",
"status": "active",
"tradable": true,
"marginable": true,
"shortable": true,
"easy_to_borrow": true,
"fractionable": true
},1. 创建账户
使用 Broker API 时，你首先需要做的一件事之一是为你的终端用户创建账户。根据你与 Alpaca 的设置类型（全披露、综合或 RIA），要求可能有所不同。
以下是针对全披露设置创建账户的示例请求：
{
"contact": {
"email_address": "test1@gmail.com",
"phone_number": "7065912538",
"street_address": [
"NG"
],
"city": "San Mateo",
"postal_code":"33345",
"state":"CA"
},
"identity": { "given_name": "John",
"family_name": "Doe",
"date_of_birth": "1990-01-01",
"tax_id_type": "USA_SSN",
"tax_id": "661-010-666",
"country_of_citizenship": "USA",
"country_of_birth": "USA",
"country_of_tax_residence": "USA",
"funding_source": [
"employment_income"
],
"annual_income_min": "10000",
"annual_income_max": "10000",
"total_net_worth_min": "10000",
"total_net_worth_max": "10000",
"liquid_net_worth_min": "10000",
"liquid_net_worth_max": "10000",
"liquidity_needs": "does_not_matter",
"investment_experience_with_stocks": "over_5_years",
"investment_experience_with_options": "over_5_years",
"risk_tolerance": "conservative",
"investment_objective": "market_speculation",
"investment_time_horizon": "more_than_10_years",
"marital_status":"MARRIED",
"number_of_dependents":5
},
"disclosures": {
"is_control_person": false,
"is_affiliated_exchange_or_finra": false,
"is_affiliated_exchange_or_iiroc": false,
"is_politically_exposed": false,
"immediate_family_exposed": false
},
"agreements": [
{
"agreement": "customer_agreement",
"signed_at": "2024-08-27T10:39:34+01:00",
"ip_address": "185.11.11.11"
},
{
"agreement": "options_agreement",
"signed_at": "2024-08-27T10:39:34+01:00",
"ip_address": "185.11.11.11"
},
{
"agreement": "margin_agreement",
"signed_at": "2020-09-11T18:09:33Z",
"ip_address": "185.13.21.99"
}
],
"documents": [
{
"document_type": "identity_verification",
"document_sub_type": "passport",
"content": "/9j/Cg==",
"mime_type": "image/jpeg"
}
],
"trusted_contact": {
"given_name": "xyz",
"family_name": "wyz",
"email_address": ""
},
"additional_information": "",
"account_type": ""
}如果成功，响应将是
{
"id": "b9b19618-22dd-4e80-8432-fc9e1ba0b27d",
"account_number": "935142145",
"status": "APPROVED",
"currency": "USD",
"last_equity": "0",
"created_at": "2021-05-17T09:53:17.588248Z"
}2. 通过 ACH 为账户注资
创建 ACH 关系
为了通过 ACH 虚拟为账户注资，我们必须首先与该账户建立 ACH 关系。
我们将使用以下端点 POST /v1/accounts/{account_id}/ach_relationships，将 account_id 替换为 b9b19618-22dd-4e80-8432-fc9e1ba0b27d
{
"account_owner_name": "Awesome Alpaca",
"bank_account_type": "CHECKING",
"bank_account_number": "32131231abc",
"bank_routing_number": "121000358",
"nickname": "Bank of America Checking"
}请确保 bank_account_number 和 bank_routing_number 的格式正确。
如果成功，你将收到如下 ach_relationship 对象：
{
"id": "c9b420e0-ae4e-4f39-bcbf-649b407c2129",
"account_id": "b9b19618-22dd-4e80-8432-fc9e1ba0b27d",
"created_at": "2021-05-17T09:54:58.114433723Z",
"updated_at": "2021-05-17T09:54:58.114433723Z",
"status": "QUEUED",
"account_owner_name": "Awesome Alpaca",
"bank_account_type": "CHECKING",
"bank_account_number": "32131231abc",
"bank_routing_number": "121000358",
"nickname": "Bank of America Checking"
}最初你将收到 status = QUEUED。
但是，如果你执行 GET/v1/accounts/{account_id}/ach_relationships，约 1 分钟后你应该会看到 status = APPROVED。
发起虚拟 ACH 转账
现在账户与其银行之间已有 ACH 关系，你可以使用以下端点 POST/v1/accounts/{account_id}/transfers 通过 ACH 为账户注资，使用我们在上一节响应中获得的 relationship_id。
{
"transfer_type": "ach",
"relationship_id": "c9b420e0-ae4e-4f39-bcbf-649b407c2129",
"amount": "1234.567",
"direction": "INCOMING"
}你应该得到的响应如下所示。
{
"id": "750d8323-19f6-47d5-8e9a-a34ed4a6f2d2",
"relationship_id": "c9b420e0-ae4e-4f39-bcbf-649b407c2129",
"account_id": "b9b19618-22dd-4e80-8432-fc9e1ba0b27d",
"type": "ach",
"status": "QUEUED",
"amount": "1234.567",
"direction": "INCOMING",
"created_at": "2021-05-17T09:56:05.445592162Z",
"updated_at": "2021-05-17T09:56:05.445592162Z",
"expires_at": "2021-05-24T09:56:05.445531104Z"
}大约 10-30 分钟后（模拟 ACH 延迟），转账应通过现金存款活动（CSD）反映在用户余额中，可通过此端点查看：GET v1/accounts/activities/CSD\?account_id\={account_id}
3. 账户之间的划转
除了通过 ACH 和电汇进行转账和注资外，我们还使组织能够直接为其公司账户注资，然后从这些账户划转到用户账户，以模拟近乎即时的注资。
介绍公司账户
每个团队在沙盒中都会获得一个预充值 $50,000 的公司账户。你可以使用此账户模拟向用户注资，或将其用于奖励计划以推动你的应用增长。
为说明我们的示例，此沙盒账户的 Sweep 账户如下所示
{
"id": "8f8c8cee-2591-4f83-be12-82c659b5e748",
"account_number": "927721227",
"status": "ACTIVE",
"currency": "USD",
"last_equity": "45064.36",
"created_at": "2021-03-03T17:50:06.568149Z"
}划转现金
对于注册奖励，或只是尝试模拟即时资金，在你的 Alpaca 公司余额与终端用户的经纪账户之间划转资金是最佳方式。
你只需传入带有 entry_type =JNLC 的请求，并选择要划转给用户的金额。
4. 提交订单
Alpaca Broker API 最常见的用例是让你的终端用户在股票市场交易。为此，只需向 POST /v1/trading/accounts/{account_id}/orders 传入请求，并同样将 account_id 替换为 b9b19618-22dd-4e80-8432-fc9e1ba0b27d
{
"symbol": "AAPL",
"qty": 0.42,
"side": "buy",
"type": "market",
"time_in_force": "day"
}无论 Alpaca 的响应是什么（由状态表示），你都应在响应中收到如下所示的 Order 模型
{
"id": "4c6cbac4-e17a-4373-b012-d446b20f9982",
"client_order_id": "5a5e2660-88a7-410c-92c9-ab0c942df70b",
"created_at": "2021-05-17T11:27:18.499336Z",
"updated_at": "2021-05-17T11:27:18.499336Z",
"submitted_at": "2021-05-17T11:27:18.488546Z",
"filled_at": null,
"expired_at": null,
"canceled_at": null,
"failed_at": null,
"replaced_at": null,
"replaced_by": null,
"replaces": null,
"asset_id": "b0b6dd9d-8b9b-48a9-ba46-b9d54906e415",
"symbol": "AAPL",
"asset_class": "us_equity",
"notional": null,
"qty": "0.42",
"filled_qty": "0",
"filled_avg_price": null,
"order_class": "",
"order_type": "market",
"type": "market",
"side": "buy",
"time_in_force": "day",
"limit_price": null,
"stop_price": null,
"status": "accepted",
"extended_hours": false,
"legs": null,
"trail_percent": null,
"trail_price": null,
"hwm": null,
"commission": "0"
}5. 事件（SSE）
你可以随时通过我们的 Events SSE 监听账户、划转记录或订单的任何事件变化。
通过此端点 GET/v1/events/journal/updates 查看划转更新的示例，其中显示 journal id = 2f144d2a-91e6-46ff-8e37-959a701cc58d 经历的所有不同阶段。
data: {"at":"2021-05-07T10:28:23.163857Z","entry_type":"JNLC","event_id":1406,"journal_id":"2f144d2a-91e6-46ff-8e37-959a701cc58d","status_from":"","status_to":"queued"}
data: {"at":"2021-05-07T10:28:23.468461Z","entry_type":"JNLC","event_id":1407,"journal_id":"2f144d2a-91e6-46ff-8e37-959a701cc58d","status_from":"queued","status_to":"pending"}
data: {"at":"2021-05-07T10:28:23.522047Z","entry_type":"JNLC","event_id":1408,"journal_id":"2f144d2a-91e6-46ff-8e37-959a701cc58d","status_from":"pending","status_to":"executed"}
你现在已准备好进一步探索 Broker API！
查看我们的 API 参考，并随时通过 Broker 仪表盘上的 Intercom 联系我们！
请求 ID
所有 Broker API 端点都会在响应头中以 X-Request-ID 键提供 API 调用的唯一标识符，请求 ID 帮助我们在系统中识别调用链。
请务必在你创建的所有支持请求中提供请求 ID，这有助于我们尽快解决问题。请求 ID 无法在其他端点中查询，因此我们建议你持久化保存近期的请求 ID。
$ curl -v https://broker-api.sandbox.alpaca.markets/v1/accounts
...
> GET /v1/accounts HTTP/1.1
> Host: broker-api.sandbox.alpaca.markets
> User-Agent: curl/7.88.1
> Accept: */*
>
< HTTP/1.1 403 Forbidden
< Date: Fri, 25 Aug 2023 09:10:03 GMT
< Content-Type: application/json
< Content-Length: 26
< Connection: keep-alive
< X-Request-ID: 65ddd35ed1b3433dbf29d11f6d932c88
<
...