概述

在你作为代币化资产发行方开始集成 Alpaca 的 ITN（即时代币化网络）之前，你需要：

• 完成你对 Alpaca Broker API 服务的集成。
• 在 Alpaca 拥有一个以你名义开设的账户。

如果你尚未这样做，请务必联系 Alpaca 销售团队以启动沟通。

如果你已完成上述步骤，以下文档将指导你集成 ITN。这将通过以下方式实现：

• 在你平台上实现 4 个 Alpaca 将用于处理账户关联和代币铸币的端点。
  • 账户关联
  • 代币化资产
  • 铸币请求
  • 铸币确认
• 集成 2 个你将用于完成代币铸币和赎回流程的 Alpaca 端点。
  • 铸币确认回调
  • 赎回请求

重要前提

在铸币和赎回过程中，即时代币化网络将在 AP 的 Alpaca 账户和发行方的 Alpaca 账户之间转移证券。如果你作为发行方在 Alpaca 持有多个账户，请务必告知 Alpaca 你的哪个账户应被指定用于代币化。

身份验证

你实现并暴露给 Alpaca 的所有端点（账户关联、代币化资产数据、铸币请求、铸币转账确认）都必须对调用方进行认证。Alpaca 支持两种方案，在入驻时按发行方选定，并在全部四个端点中统一使用：

1. API key （默认） — 你提供给 Alpaca 的共享密钥；Alpaca 会在每个请求中通过 X-API-KEY 请求头发送它。
2. HTTP 消息签名（Ed25519） — Alpaca 按 RFC 9421 使用 Ed25519 私钥对每个出站请求签名；你使用 Alpaca 在入驻时共享的公钥进行验证。请求体完整性使用 RFC 9530 Content-Digest。

你只需实现入驻时商定的方案。在两种情况下，你的端点都应对任何认证失败或缺少必需请求头的请求返回 401 Unauthorized。

方案 1：API key（默认）

在入驻期间，你与 Alpaca 共享一个密钥 API key。Alpaca 会在每个出站请求中通过以下 HTTP 请求头包含它：

X-API-KEY: <your-issuer-api-key>

全部四个由发行方实现的端点都使用同一密钥。

方案 2：HTTP 消息签名（Ed25519）

Alpaca 按 RFC 9421（HTTP 消息签名） 使用 Ed25519 密钥对每个出站请求签名。请求体完整性使用 RFC 9530（Content-Digest）。

入驻时的密钥交换

Alpaca 生成 Ed25519 密钥对，并仅与你共享公钥。你将收到两部分信息：

私钥永远不会离开 Alpaca 的环境。

Alpaca 在每个签名请求中设置的请求头

对于带请求体的请求（全部四个 POST 端点）：

POST /tokenization/mint HTTP/1.1
Content-Type: application/json
Content-Digest: sha-256=:<base64(sha256(raw-body))>:
Signature-Input: sig=("@method" "@target-uri" "content-type" "content-digest");created=<unix-seconds>;keyid="<keyid>";alg="ed25519";nonce="<128-bit random hex>"
Signature: sig=:<base64(ed25519-signature-bytes)>:

对于无请求体的请求（GET /tokenization/tokens 端点）：

GET /tokenization/tokens HTTP/1.1
Signature-Input: sig=("@method" "@target-uri");created=<unix-seconds>;keyid="<keyid>";alg="ed25519";nonce="<128-bit random hex>"
Signature: sig=:<base64(ed25519-signature-bytes)>:

关于 Alpaca 发送内容的说明：

• 签名标签始终为 sig。每个请求一个签名。
• 对于无请求体的请求，Alpaca 既不设置 Content-Type / Content-Digest，也不将其包含在签名基底中；覆盖的分量仅为 ("@method" "@target-uri")。
• created 是请求的 Unix 时间戳（以秒为单位）。
• nonce 是每个请求全新的 128 位随机熵，以十六进制编码。

示例演示

使用 keyid="alpaca-issuer-2026-01" 签名的 POST /tokenization/mint 请求会生成如下形态的请求头：

POST /tokenization/mint HTTP/1.1
Host: issuer.example.com
Content-Type: application/json
Content-Digest: sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:
Signature-Input: sig=("@method" "@target-uri" "content-type" "content-digest");created=1700000000;keyid="alpaca-issuer-2026-01";alg="ed25519";nonce="deadbeefdeadbeefdeadbeefdeadbeef"
Signature: sig=:lD6c6jHb6kQTzZ5pK6m7Bt2u8m1bF1mE4qLh3i2cIuv6xv1uYwK1Kx4G2k8nC0z3pE5p9c4r4cZ8aFwq9XnZAg==:

{"tokenization_request_id":"12345-678-90AB", ...}

密钥轮换

Alpaca 可能会定期轮换其签名密钥。Alpaca 会在商定的切换时间之前将新的公钥和新的 keyid 共享给你。在切换时间，Alpaca 切换到使用新密钥签名，从那时起每个请求的 Signature-Input 请求头都会携带新的 keyid。

数量精度

Alpaca 对标的证券数量最多接受 9 位小数。此限制同时适用于铸币和赎回流程：

• 铸币：Alpaca 绝不会要求你铸币超过 9 位小数的标的证券。任何 qty 超过 9 位小数的 AP 铸币请求都会在到达你的平台之前被 Alpaca 拒绝。
• 赎回：当你向 Alpaca 提交赎回请求时，qty（要转回给 AP 的标的证券数量）必须最多为 9 位小数。精度更高的赎回请求将被拒绝。

握手流程

在某个实体能够通过 ITN 铸币或赎回你的代币化资产之前，他们需要联系 Alpaca 的运营团队进行"握手"步骤，Alpaca 需要通过该步骤验证该实体是：

• Alpaca 的现有客户。
• 你公司的现有客户，且已在你平台上注册为授权参与者（AP）。

要自动化此流程，你需要提供一个账户关联端点，Alpaca 可用于将 AP 在 Alpaca 的账户关联到其在你平台上的账户。Alpaca 将维护此关联，并在铸币和赎回流程中使用它。

发行方的账户关联端点

Alpaca 将通过提供 AP 的电子邮件及其 Alpaca 账户号码来调用你的账户关联端点。你的端点应返回 AP 在你平台上的账户号码，Alpaca 将存储该号码以供将来在铸币和赎回流程中使用：

预期请求

端点

POST /tokenization/accounts/connect

请求体

{
  "email": "customer@firm.com",
  "client_account_number": "alpaca_account_number"
}

预期响应

请求体

{
  "client_external_account_id": "5505-1234-ABC-4G45"
}

状态码

代币化资产数据

你需要向 Alpaca 提供一个端点，用于检索你发行方平台上支持的代币化资产列表。该端点应提供以下数据：

• 标的代码
• 代币代码
• 支持的区块链网络

预期请求

端点

GET /tokenization/tokens

预期响应

请求体

{
  "tokens": [
    {
	"underlying": "AAPL",
	"token": "tAAPL",	
	"networks": ["solana", "ethereum"]
    },
    {
	"underlying": "TSLA",
  	"token": "tTSLA",
	"networks": ["solana", "ethereum"]
   }
  ]
}

Alpaca 将在验证 AP 的铸币请求时使用此信息。

动态托管账户

如果你在不同的 Alpaca 账户持有不同的标的资产，你需要向 Alpaca 提供一个动态托管账户端点。Alpaca 将使用此端点在处理铸币请求时识别你的哪个 Alpaca 账户托管某项标的资产。

你提供的 URL 必须在路径中包含 {underlying_symbol} 占位符：

https://issuer.example.com/tokenization/custody-accounts/{underlying_symbol}

Alpaca 在调用你的端点时会将 {underlying_symbol} 替换为标的资产代码。

预期请求

端点

GET /tokenization/custody-accounts/{underlying_symbol}

例如，在解析 AAPL 的托管账户时，Alpaca 将调用：

GET /tokenization/custody-accounts/AAPL

预期响应

请求体

{
  "account_id": "7d56753c-ecfa-4077-8e05-64fae3d2f3b0",
  "underlying_symbol": "AAPL"
}

你的端点必须能解析你的代币化资产端点返回的每个标的代码。Alpaca 只会针对你支持的代币化资产列表中包含的代码调用托管账户端点。

如果 Alpaca 无法解析出有效的托管账户，铸币请求将不会继续。

📘 托管账户缓存

Alpaca 会将每次成功的托管账户解析结果缓存 24 小时。如果某项标的资产转移到另一个托管账户，Alpaca 可能会继续使用之前的账户，直到缓存的解析结果过期。

铸币端点与工作流

代币铸币流程包含多个步骤，起点是 AP 向 Alpaca 请求代币铸币。以下对这些步骤进行说明，并在图 1 中加以描绘，以帮助你形象化理解，所有提到的端点也都在下方进行了说明。

1. 授权参与者向 Alpaca 发送铸币请求。
2. Alpaca 调用你平台上的一个端点来提交铸币请求，请求体中包含 JSON 对象。你的平台需要验证该铸币请求。
3. Alpaca 将标的证券从 AP 的账户转入你的 Alpaca 账户。
4. Alpaca 调用你平台上的另一个端点来确认标的资产的转账状态。
5. 转账成功后，你的平台将代币存入 AP 的钱包。
6. 你的平台调用 Alpaca 的端点来确认代币铸币成功，并在该端点的 URL 参数中提供指定的 Alpaca 代币化 account_id。

图 1. 铸币代币化资产

你需要提供的端点

发行方的铸币请求端点

此端点将在第 2 步由 Alpaca 调用。

预期请求

端点

POST /tokenization/mint

请求体

{
  "tokenization_request_id": "12345-678-90AB",
  "qty": "1.23",
  "underlying_symbol": "TSLA",
  "token_symbol": "TSLAx",
  "network": "solana",
  "client_external_account_id": "98765432",
  "wallet_address": "<AP's wallet address to deposit the tokenized asset>"
}

📘 AP 标识符

Alpaca 将发送 client_external_account_id 或 client_account_id 中的恰好一个，以标识授权参与者。特定 AP/发行方组合使用哪一个，由发行方与 Alpaca 之间的协议确定（通常，当 AP 与发行方通过握手流程关联时使用 client_external_account_id，当 AP 的代理经纪商由发行方直接授权时使用 client_account_id）。

预期响应

请求体

{
  "issuer_request_id": "123-456-ABCD-7890",
  "status": "created"
}

状态码

发行方铸币转账确认端点

此端点将在第 4 步由 Alpaca 调用。

预期请求

端点

POST /tokenization/mint/confirm

请求体

{
  "tokenization_request_id": "12345-678-90AB",
  "issuer_request_id": "ABC-123-DEF-456",
  "client_account_id": "14d484e3-46f9-4e11-99ac-6fee0d4455c7",
  "status": "<completed/rejected>"
}

📘 AP 标识符

Alpaca 会原样回显 client_account_id（关联流程）或 client_external_account_id（握手流程）中的一个，与 Alpaca 在原始铸币请求中发送给你的标识符一致。

预期响应

预期状态码

📘 此请求可能会被多次投递

当 Alpaca 收到 5xx 响应，或在收到响应之前连接失败或超时时，Alpaca 会重试该确认。每次尝试都携带相同的请求体。因此，如果你已处理了较早的某次尝试但 Alpaca 未收到其响应，重试仍可能到达你处。

将 tokenization_request_id 视为幂等键：携带相同 tokenization_request_id 的重复投递最多只能铸币一次，并且必须返回与首次投递相同的结果。4xx 响应被视为永久拒绝，不会重试。

你需要集成的端点

Alpaca 的铸币确认回调端点

此端点将在第 6 步由你的平台调用。更多详情请查阅完整的API 参考。

请求

端点

POST /v1/accounts/:account_id/tokenization/callback/mint

请求体

{
  "tokenization_request_id": "12345-678-90AB",
  "client_external_account_id": "5505-1234-ABC-4G45",
  "wallet_address": "<AP's wallet address where the tokenized assets were deposited>",
  "tx_hash": "0x12345678",
  "network": "solana"
}

📘 AP 标识符

请求体中必须提供 client_external_account_id 或 client_account_id 中的恰好一个，以标识授权参与者。特定 AP/发行方组合使用哪一个，由发行方与 Alpaca 之间的协议确定（通常，当 AP 与发行方通过握手流程关联时使用 client_external_account_id，当 AP 的代理经纪商由发行方直接授权时使用 client_account_id）。

响应

状态码

赎回端点与工作流

代币赎回流程包含多个步骤，起点是 AP 将代币存入你提供给他们的赎回钱包地址。以下对这些步骤进行说明，并在图 2 中加以描绘，以帮助你形象化理解，所有提到的端点也都在下方进行了说明。

1. 代币赎回流程将由最终客户发起，其将代币转入你作为发行方提供的赎回钱包地址，此时这些代币应从流通中移除。
2. 你的平台随后应通过调用一个端点通知 Alpaca 某 AP 已赎回其代币。你的平台应在该端点的 URL 参数中提供指定的 Alpaca 代币化 account_id。
3. Alpaca 将把标的资产从你作为发行方的 Alpaca 账户转入 AP 的 Alpaca 账户。

图 2. 赎回代币化资产

你需要集成的端点

Alpaca 的赎回请求端点

此端点将在第 2 步由你的平台调用。更多详情请查阅完整的API 参考。

请求

端点

POST /v1/accounts/:account_id/tokenization/callback/redeem

请求体

{
  "issuer_request_id": "ABC-123-DEF-456",
  "underlying_symbol": "AAPL",
  "token_symbol": "AAPLx",
  "client_external_account_id": "5505-1234-ABC-4G45",
  "qty": "1.23",
  "network": "solana",
  "wallet_address": "<the originating wallet address for the redeemed tokens>",
  "tx_hash": "0x12345678"
}

📘 AP 标识符

请求体中必须提供 client_external_account_id 或 client_account_id 中的恰好一个，以标识授权参与者。特定 AP/发行方组合使用哪一个，由发行方与 Alpaca 之间的协议确定（通常，当 AP 与发行方通过握手流程关联时使用 client_external_account_id，当 AP 的代理经纪商由发行方直接授权时使用 client_account_id）。

幂等性

每个赎回请求都必须携带你分配的唯一的 issuer_request_id。Alpaca 将其用作赎回幂等键：issuer_request_id 只能使用一次，因此重用 Alpaca 已见过的值将被拒绝并返回 422 Unprocessable Entity。

可选：Idempotency-Key 请求头

对于更严格的重复重试语义，你还可以额外发送一个可选的 Idempotency-Key HTTP 请求头。重用 issuer_request_id 会被拒绝并返回 422，而匹配的 Idempotency-Key 允许 Alpaca 重放原始响应，使自动重试能够像首次调用一样继续进行：

Idempotency-Key: <your-unique-key>

• 当存在时，去除前后空白后该值必须介于 1 到 128 个字符之间，且只能包含可打印 ASCII 字符（不含空格）。格式错误的 key 将被拒绝并返回 400 Bad Request。
• 如果 Alpaca 已处理过具有相同 Idempotency-Key 且请求体完全相同的请求，则会重放原始响应，而不会创建新的赎回请求，并且 Alpaca 会设置 Idempotent-Replayed: true 响应头。对原本状态为 rejected 的请求的重放将返回 400 Bad Request。
• 使用相同 Idempotency-Key 但请求体不同将被拒绝并返回 422 Unprocessable Entity。

响应

请求体

{
  "tokenization_request_id": "12345-678-90AB",
  "issuer_request_id": "ABCDEF123",
  "created_at": "2025-09-12T17:28:48.642437-04:00",
  "type": "redeem",
  "status": "pending",
  "underlying_symbol": "TSLA",
  "token_symbol" : "TSLAx",
  "qty" : "123.45",
  "issuer" : "xstocks",
  "network": "solana",
  "wallet_address": "0x1234567A",
  "tx_hash" : "0x1234567A"
}

其他实用端点

列出代币化请求

你可以使用以下端点列出通过你的平台执行的代币化请求。你需要在端点的 URL 参数中提供指定的 Alpaca 代币化 account_id。更多详情请查阅完整的API 参考。

请求

端点

GET /v1/accounts/:account_id/tokenization/requests

响应

请求体

[
   {
    "tokenization_request_id": "12345-678-90AB",
    "issuer_request_id": "ABCDEF123",
    "client_external_account_id": "5505-1234-ABC-4G45",
    "created_at":"2025-09-12T17:28:48.642437-04:00",
    "updated_at":"2025-09-12T17:28:48.642437-04:00",
    "type": "redeem",
    "status": "completed",
    "underlying_symbol": "TSLA",
    "token_symbol" : "TSLAx",
    "qty" : "123.45",
    "issuer" : "xstocks",
    "network": "solana",
    "wallet_address": "0x1234567A",
    "tx_hash" : "0x1234567A",
    "fees" : "0.567"
  },
  {
    "tokenization_request_id": "12345-678-90AB",
    "issuer_request_id": "ABCDEF123",
    "client_external_account_id": "5505-1234-ABC-4G45",
    "created_at":"2025-09-12T17:28:48.642437-04:00",
    "updated_at":"2025-09-12T17:28:48.642437-04:00",
    "type": "redeem",
    "status": "completed",
    "underlying_symbol": "TSLA",
    "token_symbol" : "TSLAx",
    "qty" : "123.45",
    "issuer" : "xstocks",
    "network": "solana",
    "wallet_address": "0x1234567A",
    "tx_hash" : "0x1234567A",
    "fees" : "0.567"
  },
  {
    "tokenization_request_id": "12345-678-90AB",
    "issuer_request_id": "ABCDEF123",
    "client_external_account_id": "5505-1234-ABC-4G45",
    "created_at":"2025-09-12T17:28:48.642437-04:00",
    "updated_at":"2025-09-12T17:28:48.642437-04:00",
    "type": "redeem",
    "status": "completed",
    "underlying_symbol": "TSLA",
    "token_symbol" : "TSLAx",
    "qty" : "123.45",
    "issuer" : "xstocks",
    "network": "solana",
    "wallet_address": "0x1234567A",
    "tx_hash" : "0x1234567A",
    "fees" : "0.567"
  }
]

按 ID 获取代币化请求

通过 Alpaca 分配的 tokenization_request_id 获取单条代币化请求。返回的对象与列出代币化请求响应中的单个条目相同。

请求

端点

GET /v1/accounts/:account_id/tokenization/requests/:tokenization_request_id

状态码

按发行方请求 ID 获取代币化请求

通过你在提交赎回请求时分配的 issuer_request_id 获取单条代币化请求。返回的对象与列出代币化请求响应中的单个条目相同。

请求

端点

GET /v1/accounts/:account_id/tokenization/requests:by_issuer_request_id?issuer_request_id=<your-value>

状态码

术语表

• 授权参与者：获许可在代币化资产（例如 xstocks）中开展数字资产业务的实体。发行方仅向授权参与者（AP）出售代币化资产。AP 可以将代币化资产出售给其客户。
• 发行方：购买标的股权证券、将其包装并创建/发行由该证券支持的代币的金融实体。
• 铸币：将标的股权证券转换为代币化资产的行为。
• 赎回：将代币化资产转换为其标的股权证券的行为。

Alpaca 的即时代币化网络由 AlpacaDB, Inc. 和 Alpaca Crypto LLC 拥有和开发。根据当地监管要求，代币化服务可能适用额外地域限制。Alpaca Crypto LLC 和 Alpaca Securities LLC 均不是任何资产代币化的发行方，也不直接参与其中。代币化由第三方执行。代币化资产不表示对任何标的公司或发行方的直接股权所有权。相反，代币化资产通常提供对标的发行方股权证券的经济敞口。因此，除非明确说明，代币化资产持有人在标的公司清算或破产时对标的公司股份或任何剩余资产不享有投票权、股息权利或法律主张。所有投资均涉及风险。更多信息请参阅我们的代币化风险披露。