加密货币钱包 API | Alpaca 简体中文

请注意，你需要联系 Alpaca 以启用 Crypto Wallets API 访问权限。请联系你的客户成功经理或销售代表为你启用此功能。

概述

Alpaca Crypto Wallets API 使你能够在 Alpaca 账户内入金、提现和管理加密货币资产。本文档说明了如何使用 Alpaca 的 Crypto Wallets API 以加密资产（如 USDC）测试入金账户、验证转账并开始交易。

支持的资产

支持的 Testnet 和水龙头（Sandbox）

要测试不同资产在支持的区块链网络上的入金和提现流程，你可以使用以下 testnet 水龙头。务必确保你在正确的网络上请求代币并进行交互（例如 Ethereum Sepolia、Solana Devnet）。

稳定币

USDC（支持 Testnet/Devnet）
- 网络：Ethereum Sepolia、Solana Devnet
- 水龙头：Circle Testnet 水龙头
USDG（支持 Testnet）
- 网络：Ethereum Sepolia、Solana Devnet
- 水龙头：Paxos 水龙头
USDT（Testnet）
- 网络：Ethereum Sepolia
- 水龙头：
  - WeenusTokenFaucet GitHub
  - 合约地址：Etherscan 上的 0x7439...fB9

BTC（Testnet）

tBTC — Bitcoin Testnet4 水龙头

Solana（Devnet）

Solana Devnet 水龙头 – 空投 SOL

ETH（Sepolia）

XRP（Testnet）

XRPL Tesnet 水龙头

入门指南：Sandbox 测试指南

步骤 1：生成你的入金钱包地址

为所需资产创建或获取你的加密货币入金钱包地址：

GET /v1/accounts/{account_id}/wallets?asset=USDC&network=ethereum

响应：

{
    "asset_id": "5d0de74f-827b-41a7-9f74-9c07c08fe55f",
    "address": "0x42a76C83014e886e639768D84EAF3573b1876844",
    "created_at": "2025-08-07T08:52:40.656166Z"
}

步骤 2：为你的钱包充值（Sandbox）

用于 USDC 测试：

访问 Circle Sepolia 水龙头：https://faucet.circle.com
粘贴你在步骤 1 中获得的钱包地址
点击 Send
等待 ~12 个区块确认（通常 2-3 分钟）

步骤 3：验证入金

监控入账转账以确认你的入金：

选项 1：轮询 transfers API

GET /v1/accounts/{account_id}/wallets/transfers

响应：

[
    {
        "id": "876b1c4f-df5e-4d1b-beaa-81af7f7bd02c",
        "tx_hash": "0xaca1f6ba105a68771d966b4ce17e0992ad3d8030d127cdb18e113efa3a864992",
        "direction": "INCOMING",
        "amount": "10",
        "usd_value": "9.99707",
        "chain": "ETH",
        "asset": "USDC",
        "from_address": "0x3C3380cdFb94dFEEaA41cAD9F58254AE380d752D",
        "to_address": "0x42a76C83014e886e639768D84EAF3573b1876844",
        "status": "COMPLETE",
        "created_at": "2025-08-07T10:31:41.964121Z",
        "network_fee": "0",
        "fees": "0"
    },
    {
        "id": "bf31ecca-e28c-4f9a-8e81-12bbf79836fd",
        "tx_hash": "0x849de6f0f225c18b58f3dea5a76a42a0dcba4902ce069147bb0dcd585a3e699b",
        "direction": "INCOMING",
        "amount": "5",
        "usd_value": "4.998794999999999",
        "chain": "ETH",
        "asset": "USDC",
        "from_address": "0xf38Ecf5764fD2dEcB0dd9C1E7513a0b6eC0dD08a",
        "to_address": "0x42a76C83014e886e639768D84EAF3573b1876844",
        "status": "COMPLETE",
        "created_at": "2025-08-08T11:13:26.263719Z",
        "network_fee": "0",
        "fees": "0"
    }
]

状态值：

PROCESSING：交易已提交至区块链
COMPLETE：资金可用于交易
FAILED：交易失败

选项 2：NTA SSE 事件

显示入金到账的示例事件：

{
    "id": "a6a3f62c-d4dd-4b6f-9b3a-fb65892c9695",
    "qty": 10,
    "cusip": "USDC12345",
    "status": "executed",
    "symbol": "USDCUSD",
    "entry_type": "OCT",
    "net_amount": 0,
    "description": "Deposit Transaction, transfer_id: 296f3a5b-72e8-4ec6-b1fe-77048e77e87f, tx_hash: 0x97fa0e98598d7bedf2871bc1846daa076cddafaa9046b3697b6cd89ca7304932",
    "settle_date": "2025-09-19",
    "system_date": "2025-09-19",
    "price": "0.9997",
    "per_share_amount": null,
    "account_id": "34c18dbe-0983-4e61-b493-9578714dae23",
    "at": "2025-09-19T08:09:01.061337Z",
    "event_ulid": "01K5GG9ZC5A3CVKP5QEZ79PVEX"
}

步骤 4：使用已入金资产进行交易（可选）

通过以 USD 卖出你的入金加密货币，将其转换为 USD 购买力：

POST /v1/trading/accounts/{account_id}/orders

请求体：

{
  "symbol": "USDC/USD",
  "qty": "50",
  "side": "sell",
  "type": "market", 
  "time_in_force": "day"
}

步骤 5：开始交易

一旦你的 USDC 转换为 USD 购买力，你可以：

交易股票和 ETF
交易其他加密货币交易对

要查看你的 USD 购买力，你可以调用 Retrieve Trading Details for an Account API 端点，并查找 buying_power。

提现加密资产

概述

从你的 Alpaca 账户提取加密货币需要经过多步流程以确保资金安全：

白名单目标地址并附上旅行规则信息
验证白名单批准状态
请求向已批准的地址提现
监控提现状态

步骤 1：将目标地址加入白名单

提现之前，你必须为目标钱包地址添加白名单并附上旅行规则信息。根据你发送资金的钱包类型及其所在交易所的司法管辖区，我们可能需要收集更多信息。我们提供了几种可用于提供旅行规则信息的方法示例。任何方法都可以使用自然人姓名或实体名称。更多信息请参阅下面的“实体信息”部分。

POST v1/accounts/{account_id}/wallets/whitelists

示例 1：自托管/非托管钱包

此处的自托管是指不由交易所托管的钱包。

{
  "address": "0xf38Ecf5764fD2dEcB0dd9C1E7513a0b6eC0dD08a",
  "asset": "USDC",
  "travel_rule_info": {
    "beneficiary_is_self_hosted": true,
    "beneficiary_given_name": "John",
    "beneficiary_family_name": "Doe"
  }
}

示例 2：通过搜索端点找到的交易所（首选方法）

请使用我们的 Search for VASPs 端点，找到你的钱包地址所属交易所的 VASP DID。下面列出的 VASP DID 适用于我们的美国交易所。

{
  "address": "0xf38Ecf5764fD2dEcB0dd9C1E7513a0b6eC0dD08a",
  "asset": "USDC",
  "travel_rule_info": {
    "beneficiary_vasp_id": "did:ethr:0xf1c002f9e7ca88018d6dcf1e86403fb2f5f055f4",
    "beneficiary_given_name": "John",
    "beneficiary_family_name": "Doe"
  }
}

示例 3：未列出的交易所

如果你的交易所无法通过 Search for VASPs 端点找到，你可以手动提供有关该交易所的信息。

{
  "address": "0xf38Ecf5764fD2dEcB0dd9C1E7513a0b6eC0dD08a",
  "asset": "USDC",
  "travel_rule_info": {
    "beneficiary_manual_entry": {
        "vasp_name": "The Unlisted Exchange",
        "vasp_website": "https://unlisted.exchange"
    },
    "beneficiary_given_name": "John",
    "beneficiary_family_name": "Doe"
  }
}

实体信息

如果你的受益人是实体，你可以填写 beneficiary_entity_name。请注意，你不能在实体名称之外同时提交 beneficiary_given_name 和 beneficiary_family_name。你必须选择其中一种选项。

未能提供正确的受益人信息可能导致你的提现被对手方交易所拒绝（如适用）。请参阅下面的请求载荷，其中展示了如何为钱包地址添加白名单，并附带实体信息以及通过 Search for VASPs 端点找到的 VASP ID。你也可以使用前面的示例 1 和 3 提供实体信息，用你实体的名称替换自然人。

{
  "address": "0xf38Ecf5764fD2dEcB0dd9C1E7513a0b6eC0dD08a",
  "asset": "USDC",
  "travel_rule_info": {
    "beneficiary_vasp_id": "did:ethr:0xf1c002f9e7ca88018d6dcf1e86403fb2f5f055f4",
    "beneficiary_entity_name": "Alpaca Crypto LLC"
  }
}

成功响应：

[
    {
        "id": "45efdedd-28cd-4665-98b4-601d5f34ae0a",
        "chain": "ETH",
        "asset": "USDC",
        "address": "0xf38Ecf5764fD2dEcB0dd9C1E7513a0b6eC0dD08a",
        "created_at": "2025-08-07T13:16:46.49111Z",
      	"status": "PENDING",
      	"travel_rule_info": {
            "beneficiary_vasp_id": "did:ethr:0xf1c002f9e7ca88018d6dcf1e86403fb2f5f055f4",
            "beneficiary_entity_name": "Alpaca Crypto LLC"
        }
    }
]

错误响应 - BENEFICIARY_NAME_REQUIRED：

如果你没有为受益人提供自然人姓名或实体名称，或者同时提供了两者，将返回此错误。请按照 ONE_OF 要求只选择其中一个选项。

{
    "error_code": "BENEFICIARY_NAME_REQUIRED",
    "message": "Please provide the beneficiary's name. Select one of the following options.",
    "next_actions": [
        {
            "name": "supply_beneficiaryName_naturalPerson",
            "description": "Provide the recipient's first and last name.",
            "type": "ONE_OF",
            "required_fields": [
                {
                    "field": "beneficiary_given_name",
                    "value_type": "string",
                    "description": "The recipient's first name."
                },
                {
                    "field": "beneficiary_family_name",
                    "value_type": "string",
                    "description": "The recipient's last name."
                }
            ]
        },
        {
            "name": "supply_beneficiaryName_legalEntity",
            "description": "Provide the entity's legal name.",
            "type": "ONE_OF",
            "required_fields": [
                {
                    "field": "beneficiary_entity_name",
                    "value_type": "string",
                    "description": "The legal name of the receiving entity."
                }
            ]
        }
    ]
}

错误响应 - TRAVEL_RULE_ACTION_REQUIRED：

如果我们的旅行规则信息载荷缺少信息，将返回此错误。这个特定的错误载荷会在你向加拿大交易所提取资金时发送，但也可能在其他场景下与其他 next_actions 一起显示。

{
  "error_code": "TRAVEL_RULE_ACTION_REQUIRED",
  "message": "We require more information to whitelist this wallet address. Please provide the requested information.",
  "next_actions": [
    {
      "name": "supply_beneficiaryGeographicAddress",
      "description": "The receiver's geographic address.",
      "type": "REQUIRED",
      "required_fields": [
        {
          "field": "beneficiary_geographic_address_street_name",
          "value_type": "string",
          "description": "The receiver's street name.",
        },
        {
          "field": "beneficiary_geographic_address_post_code",
          "value_type": "string",
          "description": "The receiver's post code.",
        },
        {
          "field": "beneficiary_geographic_address_town_name",
          "value_type": "string",
          "description": "The receiver's town name.",
        },
        {
          "field": "beneficiary_geographic_address_country",
          "value_type": "string",
          "description": "The receiver's country as an ISO 3166 Alpha-2 string (two letters only).",
        },
        {
          "field": "beneficiary_geographic_address_building_number",
          "value_type": "string",
          "description": "The receiver's building number. Use 'UNKNOWN' if you are unsure.",
        }
      ]
    }
  ]
}

错误响应 - UNKNOWN_VASP：

如果我们找不到你提供的 VASP ID，或者你的手动输入匹配到了多个 VASP ID，将返回此错误。如果你的受益人交易所拥有多个实体，就可能发生这种情况。

{
    "error_code": "UNKNOWN_VASP",
    "message": "We are unable to find the requested VASP.",
    "next_actions": [
        {
            "name": "select_vasp",
            "type": "REQUIRED",
            "description": "Select the beneficiary's VASP from our directory. Use the '/v1/wallets/travel-rule/vasps' endpoint to search. Submit the chosen 'id' in the 'travel_rule_info.beneficiary_vasp_id' field.",
            "required_fields": [
                {
                    "field": "beneficiary_vasp_id",
                    "value_type": "string",
                    "description": "The beneficiary's VASP ID.",
                }
            ]
        }
    ]
}

错误响应 - ADDRESS_BELONGS_TO_VASP：

如果你将已知的交易所钱包声明为自托管钱包，将返回此错误。要修复该错误，你必须使用旅行规则信息声明中提供的详细信息。

{
  "error_code": "ADDRESS_BELONGS_TO_VASP",
  "message": "We have detected that the address you specified belongs to Alpaca (US) (did:ethr:0xf1c002f9e7ca88018d6dcf1e86403fb2f5f055f4)",
  "next_actions": [
    {
      "name": "remove_self_hosted_declaration",
      "type": "REQUIRED",
      "description": "You must remove the `self-hosted` declaration.",
      "required_fields": [
        {
          "field": "beneficiary_is_self_hosted",
          "value_type": "bool",
          "description": "True if the destination is a self-hosted (unhosted).",
          "options": [
            {
              "value": "false",
              "description": "The destination is not a self-hosted wallet."
            }
          ]
        }
      ]
    },
    {
      "name": "set_beneficiary_vasp_did",
      "type": "REQUIRED",
      "description": "You must set `beneficiary_vasp_id` as displayed below.",
      "required_fields": [
        {
          "field": "beneficiary_vasp_id",
          "value_type": "string",
          "description": "The detected beneficiary's VASP ID.",
          "options": [
            {
              "value": "did:ethr:0xf1c002f9e7ca88018d6dcf1e86403fb2f5f055f4",
              "description": "The beneficiary's VASP ID"
            }
          ]
        }
      ]
    }
  ]
}

步骤 2：检查白名单批准状态

监控你的白名单地址以确认批准（24 小时内）：

GET v1/accounts/{account_id}/wallets/whitelists

响应：

[
    {
        "id": "45efdedd-28cd-4665-98b4-601d5f34ae0a",
        "chain": "ETH",
        "asset": "USDC",
        "address": "0xf38Ecf5764fD2dEcB0dd9C1E7513a0b6eC0dD08a",
        "created_at": "2025-08-07T13:16:46.49111Z",
        "status": "APPROVED"
    }
]

步骤 3：请求提现

一旦批准，创建一笔提现转账：

POST /v1/accounts/{account_id}/wallets/transfers

请求体：

{
 "amount": "55",
 "address": "34c18dbe-0983-4e61-b493-9578714dae23",
 "asset": "USDC"
}

响应：

{
    "id": "f8fe06fe-702e-4d79-802c-f31cb1677f7c",
    "tx_hash": null,
    "direction": "OUTGOING",
    "amount": "55",
    "usd_value": "54.9725",
    "chain": "ETH",
    "asset": "USDC",
    "from_address": "0xA0D2C7210D7e2112A4F7888B8658CB579226dB3B",
    "to_address": "0xf38Ecf5764fD2dEcB0dd9C1E7513a0b6eC0dD08a",
    "status": "PROCESSING",
    "created_at": "2025-09-19T08:37:25.436307Z",
    "network_fee": "20",
    "fees": "0.3025"
}

步骤 4：监控提现状态

跟踪你的提现进度：

选项 1：轮询 transfers API

GET /v1/accounts/{account_id}/wallets/transfers

响应：

[ {
        "id": "f8fe06fe-702e-4d79-802c-f31cb1677f7c",
        "tx_hash": null,
        "direction": "OUTGOING",
        "amount": "55",
        "usd_value": "54.9725",
        "chain": "ETH",
        "asset": "USDC",
        "from_address": "0xA0D2C7210D7e2112A4F7888B8658CB579226dB3B",
        "to_address": "0xf38Ecf5764fD2dEcB0dd9C1E7513a0b6eC0dD08a",
        "status": "PROCESSING",
        "created_at": "2025-09-19T08:37:25.436307Z",
        "network_fee": "0",
        "fees": "0.3025"
    }
]

选项 2：NTA SSE 事件

显示出账提现的示例事件：

{
    "id": "a554262e-71dc-4a02-a0c0-271bcb9480e4",
    "qty": -54.6975,
    "cusip": "USDC12345",
    "status": "executed",
    "symbol": "USDCUSD",
    "entry_type": "OCT",
    "net_amount": 0,
    "description": "Withdrawal Transaction, transfer_id: f8fe06fe-702e-4d79-802c-f31cb1677f7c, tx_hash: 0xceaf451d26a11aa43681e6f9336987325b6c1c347d64f59b45811050d8789a24",
    "settle_date": "2025-09-19",
    "system_date": "2025-09-19",
    "price": "0.9995",
    "per_share_amount": null,
    "account_id": "34c18dbe-0983-4e61-b493-9578714dae23",
    "at": "2025-09-19T08:46:59.821881Z",
    "event_ulid": "01K5GJFGQDE4WQME5F38ZTXSTS"
}

根据你与提现交易关联的代理行配置，你可能还会看到 CFEE。

{
    "id": "5abfdea7-de14-4985-8632-428e8ffb7aa5",
    "qty": 1.3475,
    "cusip": "USDC12345",
    "status": "executed",
    "symbol": "USDCUSD",
    "entry_type": "CFEE",
    "net_amount": 0,
    "description": "Wallet Correspondent Transaction Fee, transfer_id: f8fe06fe-702e-4d79-802c-f31cb1677f7c, tx_hash: 0xceaf451d26a11aa43681e6f9336987325b6c1c347d64f59b45811050d8789a24",
    "settle_date": "2025-09-19",
    "system_date": "2025-09-19",
    "price": "0.9995",
    "per_share_amount": null,
    "account_id": "34c18dbe-0983-4e61-b493-9578714dae23",
    "at": "2025-09-19T08:46:59.819319Z",
    "event_ulid": "01K5GJFGQBCWVHV4YDV13QW68V"
}

{
    "id": "106a8e17-af4f-4dd1-a0a7-463ea035cb12",
    "qty": -0.275,
    "cusip": "USDC12345",
    "status": "executed",
    "symbol": "USDCUSD",
    "entry_type": "CFEE",
    "net_amount": 0,
    "description": "Wallet Transaction Fee, transfer_id: f8fe06fe-702e-4d79-802c-f31cb1677f7c, tx_hash: 0xceaf451d26a11aa43681e6f9336987325b6c1c347d64f59b45811050d8789a24",
    "settle_date": "2025-09-19",
    "system_date": "2025-09-19",
    "price": "0.9995",
    "per_share_amount": null,
    "account_id": "34c18dbe-0983-4e61-b493-9578714dae23",
    "at": "2025-09-19T08:46:59.821196Z",
    "event_ulid": "01K5GJFGQDDT69PTT6K37N1CQN"
}

{
    "id": "472f9c57-22b7-41a0-82b2-396e51fb99cf",
    "qty": -1.375,
    "cusip": "USDC12345",
    "status": "executed",
    "symbol": "USDCUSD",
    "entry_type": "CFEE",
    "net_amount": 0,
    "description": "Wallet Correspondent Transaction Income, transfer_id: f8fe06fe-702e-4d79-802c-f31cb1677f7c, tx_hash: 0xceaf451d26a11aa43681e6f9336987325b6c1c347d64f59b45811050d8789a24",
    "settle_date": "2025-09-19",
    "system_date": "2025-09-19",
    "price": "0.9995",
    "per_share_amount": null,
    "account_id": "34c18dbe-0983-4e61-b493-9578714dae23",
    "at": "2025-09-19T08:46:59.821937Z",
    "event_ulid": "01K5GJFGQDE5RGMVCJBDS42K0P"
}