一、Ledger Enterprise 平台架构概览
Ledger Enterprise（前身为 Ledger Vault）是面向机构、托管方、加密银行与专业投资者的企业级数字资产托管平台，核心架构由硬件安全层 + API 服务层 + 治理规则引擎三层构成，通过 RESTful API 开放全部托管能力，支持企业将加密资产业务无缝集成到自有后台系统。
1.1 核心安全架构
私钥隔离存储：主种子由 HSM（硬件安全模块）离线生成与保护，私钥永不触网、永不离开安全元件；
多授权治理模型：所有交易、账户变更、权限调整均需满足预设审批规则（M-of-N 多签），单人无法独立执行敏感操作；
审计日志全链路留痕：每一次 API 调用、审批动作、签名操作均生成不可篡改的审计记录，满足合规审计要求。
1.2 API 版本与接入域名
稳定版 v1：https://api.vault.ledger.com/v1/rest，生产环境使用，兼容全部企业功能；
新一代 Revault API：https://revault.vault.ledger.com，主打读取性能优化与数据实时性，适合高频查询场景；
沙箱环境：提供独立测试域名与测试账户，支持完整功能联调，不涉及真实资产。
二、认证体系：双重身份校验机制
Ledger Enterprise API 采用 API User + JWT Bearer Token 双重认证，区别于普通单密钥 API，从源头杜绝密钥泄露导致的资产风险。
2.1 认证流程
创建 API User：管理员在企业后台创建 API 服务账号，分配角色与权限范围，生成 api_user_id 与 api_key_secret；
获取访问令牌：使用 API User 凭证调用认证端点，获取有效期 24 小时的 JWT Access Token；
携带令牌请求：所有业务接口请求头携带 Authorization: Bearer {{access_token}}；
令牌刷新：Token 过期前通过 Refresh Token 续期，避免频繁传递主密钥。
2.2 权限粒度控制
账户级权限：API User 仅可访问授权的特定账户，无法查看全企业资产；
操作级权限：区分只读、创建交易、审批交易、管理用户等细粒度角色；
IP 白名单：可绑定 API 调用源 IP 范围，非白名单 IP 直接拒绝请求。
三、核心 API 模块与典型端点
3.1 账户管理（Accounts）
表格
方法 端点 功能说明
GET /accounts 分页查询授权账户列表，支持按币种、账户名筛选
GET /accounts/{account_id} 查询单个账户详情，含余额、地址、币种、状态
GET /accounts/{account_id}/addresses 获取账户链上地址列表，支持新地址派生
POST /accounts 创建新托管账户，指定币种、账户名、治理规则
示例请求：查询账户列表
bash
运行
curl --request GET \
--url https://api.vault.ledger.com/v1/rest/accounts \
--header 'authorization: Bearer {{access_token}}' \
--header 'content-type: application/json'
3.2 交易引擎（Transactions）
交易模块是企业 API 的核心，支持链上转账、智能合约交互、质押、NFT 操作等全场景，全部遵循「创建 → 审批 → 签名 → 广播」四步治理流程。
表格
方法 端点 功能说明
POST /transactions 创建交易草稿，指定发送账户、接收地址、金额、Gas 参数
GET /transactions 查询交易列表，支持按状态、币种、时间范围筛选
GET /transactions/{tx_id} 查询单笔交易详情，含审批进度、链上哈希、区块确认数
POST /transactions/{tx_id}/approve 审批交易，满足治理规则后自动触发硬件签名
POST /transactions/{tx_id}/reject 拒绝交易，附拒绝原因
3.3 智能合约交互（Smart Contract）
支持以太坊及所有 EVM 兼容链的智能合约调用，可实现 DEX 交易、DeFi 质押、NFT mint / 转账、流动性提供等复杂 Web3 操作。
核心参数：
contract_address：目标合约地址；
contract_input：合约调用数据，支持 ABI 编码格式与原始 hex 两种传入方式；
value：转账原生代币数额（如 ETH 主币）；
gas_limit / gas_price：自定义 Gas 参数，也可使用平台自动估算。
典型场景：
DeFi 协议质押、解质押、领取奖励；
Uniswap / 1inch 等 DEX 兑换交易；
NFT 铸造、转移、挂单、授权；
多签钱包（Safe）合约调用。
3.4 质押服务（Staking）
原生支持 Polkadot、以太坊、Solana 等主流 POS 链的质押操作，可通过 API 一键完成质押、解质押、奖励查询，收益自动归集到托管账户。
表格
方法 端点 功能
POST /staking/bond 质押代币，绑定验证节点
POST /staking/unbond 解除质押，进入解锁周期
GET /staking/rewards 查询质押奖励累计与发放记录
3.5 用户与治理（Users & Governance）
/users：管理企业成员账户、角色分配、权限变更；
/groups：创建审批组，配置 M-of-N 多签规则；
/policies：配置交易策略，如地址白名单、单笔限额、每日累计限额、时间锁。
四、审批工作流：治理规则引擎集成
Ledger Enterprise API 的核心差异化能力是可编程治理规则，企业可根据自身合规与风控要求，通过 API 配置复杂审批流程，所有交易强制执行。
4.1 治理规则类型
金额阈值规则：小额交易单人审批即可，大额交易需多人联签；
地址白名单规则：仅允许向预设地址转账，陌生地址交易自动拦截；
角色分离规则：交易创建者不可同时为审批者，实现操作与审核分离；
时间锁规则：大额交易设置 24/48 小时延迟执行窗口，窗口期内可撤回；
币种专属规则：不同币种、不同账户独立配置审批策略。
4.2 API 集成审批流程
业务系统调用 POST /transactions 创建交易；
平台根据治理规则自动匹配审批组，生成待审批任务；
审批人通过硬件钱包签名确认（或 API 审批接口）；
达到 M-of-N 法定人数后，HSM 自动执行硬件签名并广播上链；
链上确认后回调通知业务系统，更新交易状态。
五、Webhook 事件回调：实时状态同步
企业系统无需轮询查询交易状态，通过配置 Webhook 端点接收实时事件推送，实现业务流自动化。
5.1 支持的事件类型
transaction.created：新交易创建；
transaction.approved：交易获得审批；
transaction.signed：交易完成硬件签名；
transaction.broadcasted：交易已广播上链；
transaction.confirmed：交易获得区块确认；
transaction.failed：交易执行失败；
account.balance_updated：账户余额变动。
5.2 安全校验
每个 Webhook 请求携带签名头，业务端需使用 Webhook Secret 验签，防止伪造回调；
失败自动重试，最多重试 5 次，间隔指数递增，确保事件不丢失。
六、最佳实践与安全集成建议
6.1 开发集成建议
沙箱优先：所有功能先在沙箱环境完成联调，验证通过后再切生产；
幂等设计：创建交易时携带自定义 request_id，避免网络超时导致重复创建；
分页处理：账户、交易列表接口均支持游标分页，大数据量场景务必分页拉取；
错误码处理：封装统一错误处理逻辑，针对 401 令牌过期、429 限流、403 权限不足 做分支处理。
6.2 安全加固建议
API 密钥分离存储：api_key_secret 存入企业密钥管理系统（KMS），禁止硬编码在代码或配置文件；
最小权限原则：每个业务系统创建独立 API User，仅分配必要的账户与操作权限；
IP 白名单绑定：生产环境强制开启 IP 白名单，限制 API 调用来源；
审计日志对接：将 API 调用日志与企业 SIEM 系统打通，实时监控异常调用行为；
硬件审批不替代：关键交易仍需管理员通过 Ledger 硬件设备物理确认，API 仅完成流程编排，不绕过硬件签名环节。
