SDK API 参考

按功能查找 StashWalletClient 方法。每个方法分别列出调用、参数和返回值，复杂类型放在可展开的定义中。

阅读约定

所有请求方法返回 Promise，失败时拒绝 Promise。下文的返回类型描述 SDK 契约，不保证当前钱包一定支持。实际行为以运行时能力、钱包校验和用户审批为准。

客户端创建

创建客户端（推荐）

网页接入时，推荐使用 StashWalletClient.connect() 创建客户端。它会等待钱包扩展向页面注入 Provider，避免页面刚加载时因 Provider 尚未就绪而创建失败。

import { StashWalletClient } from 'stash-wallet-sdk'

const client = await StashWalletClient.connect()

参数与返回值

timeoutMs：可选，等待 Provider 的超时时间，单位为毫秒，默认 5000。传入该参数时，它也会用于后续钱包请求的超时设置。
返回 Promise<StashWalletClient>，成功后可使用客户端调用钱包接口。

创建客户端不会弹出站点授权请求。需要连接用户钱包时，再调用实例的 connect()：

const account = await client.connect()
console.log(account.address)

如果未检测到钱包扩展，创建操作会失败，并返回 PROVIDER_NOT_FOUND 错误。页面应提示用户安装或启用 Stash Wallet 扩展，然后刷新页面重试。

使用构造函数创建客户端

如果页面中的钱包 Provider 已经就绪，也可以直接创建客户端：

const client = new StashWalletClient()

构造函数不会等待 Provider 注入。SDK 会先检测页面中的 Provider，再尝试通过 Chrome 扩展通信；如果两种方式都不可用，则返回 PROVIDER_NOT_FOUND 错误。

需要自定义通信方式时，可通过可选的 transport 参数传入 Transport 实例。配置示例见 Provider 与事件。

检查扩展是否已检测到

isInstalled() 返回 SDK 是否检测到钱包 Provider 或扩展标记，可用于显示页面中的安装提示。

const detected = client.isInstalled()

返回值为 boolean。true 只表示已检测到扩展，不表示钱包已解锁或用户已授权。此方法需要已有客户端实例；首次接入时，请使用上面的 StashWalletClient.connect() 创建客户端并处理失败结果。

连接与账户

connect

请求用户批准站点连接。

client.connect()
// Promise<ConnectResult>

返回值

interface ConnectResult {
  address: string
}

disconnect

撤销当前 origin 的站点授权，不锁定整个钱包。

client.disconnect()
// Promise<boolean>

getAccounts

查询账户信息。返回的是对象，不是账户数组。

client.getAccounts()
// Promise<AccountsResult>

返回值

interface AccountsResult {
  address: string
  btc_pub: string
  rgb_pub: string
}

getBtcAddress

client.getBtcAddress()
// Promise<BtcAddressResponse>

返回值

interface BtcAddressResponse {
  address: string
  network: Network
}

会话、网络与能力

getWalletSessionStatus

client.getWalletSessionStatus()
// Promise<WalletSessionStatus>

返回值

interface WalletSessionStatus {
  status: 'locked' | 'unlocked' | 'not_configured'
  network: Network | null
}

getNetwork

client.getNetwork()
// Promise<{ network: Network }>

网络类型

type Network = 'mainnet' | 'testnet' | 'testnet4' | 'regtest'

实际支持范围必须查询 supportedNetworks，不能只依据类型判断。

switchNetwork

可能需要用户审批或等待网络切换。完成后重新查询状态和能力。

client.switchNetwork(network)
// Promise<{ network: Network; switched: boolean }>

参数：network 为目标 Network。

getVersion

client.getVersion()
// Promise<{ version: string }>

getCapabilities

查询当前运行时能力。

client.getCapabilities()
// Promise<ProviderCapabilities>

返回类型：ProviderCapabilities

interface ProviderCapabilities {
  protocolVersion: string
  providerVersion: string
  canConnect: boolean
  canIssue: boolean
  canClaim: boolean
  canSwap: boolean
  canLsp: boolean
  canLspRevoke: boolean
  canAuthSign: boolean
  authNetworks: Network[]
  supportedNetworks: Network[]
}

身份与消息签名

requestAuthSignature

client.requestAuthSignature(params)
// Promise<AuthSignatureResponse>

参数：AuthSignatureRequest，必须明确指定版本 1 或 2。完整请求、响应与验证流程见 Auth 登录。

signMessage

普通消息签名，不能替代 Auth challenge 协议。

client.signMessage(params)
// Promise<SignMessageResult>

参数与返回值

interface SignMessageRequest {
  message: string
  origin?: string
}

interface SignMessageResult {
  pubkey: string
  sign: string
}

来源校验

origin 不能用于冒充其他站点。扩展使用浏览器 sender 确定实际来源。

RGB 资产查询

getRgbUtxos

client.getRgbUtxos()
// Promise<RgbUtxoItem[]>

返回类型：RgbUtxoItem

interface RgbUtxoItem {
  outpoint: string
  reserved: boolean
  value_sats?: string
  confirmed_height?: number
  assets?: {
    contract_id: string
    amount: string
  }[]
}

getContractBalance

client.getContractBalance(contract_id)
// Promise<ContractBalanceResult>

参数：contract_id 为合约 ID 字符串。

返回值

interface ContractBalanceResult {
  contract_id: string
  confirmed: string
  unconfirmed: string
}

金额精度

金额字符串不要直接转换为可能丢失精度的 JavaScript number；展示时结合资产 precision 处理。

isContractKnown

client.isContractKnown(contract_id)
// Promise<ContractKnownResult>

参数：contract_id 为合约 ID 字符串。

返回值

interface ContractKnownResult {
  contract_id: string
  known: boolean
}

合约导入与发行

importContract

client.importContract(params)
// Promise<{ contract_id: string }>

参数

interface ImportContractRequest {
  contract_id: string
  consignment_key?: string
  origin?: string
}

autoImportContract

client.autoImportContract(contract_id)
// Promise<{ contract_id: string; source: string; public_url?: string }>

参数：contract_id 为合约 ID 字符串。

issueContract

client.issueContract(params)
// Promise<{ id: string }>

参数

interface IssueContractRequest {
  ticker: string
  name: string
  supply: number
  precision: number
  seal?: string
  origin?: string
}

供给量与精度必须符合钱包校验，不要传入超出安全整数范围的数量。接口存在不代表钱包当前支持发行。

比特币、RGB 与闪电支付

资金操作

页面确认不是钱包授权。超时不代表支付取消；先核查权威交易或支付状态，避免重复付款。不要记录敏感凭据或不必要的支付 preimage。

sendBitcoin

client.sendBitcoin(params)
// Promise<{ txid: string }>

参数

interface SendBitcoinRequest {
  toAddress: string
  satoshis: number
  feeRate?: number
  origin?: string
}

satoshis：单位为 sat，不是 BTC。
feeRate：SDK 类型未定义单位或默认值，提交前应对照目标钱包版本确认。

sendRGB

client.sendRGB(params)
// Promise<{ payment_id: string; txid?: string }>

参数

interface SendRGBRequest {
  invoice: string
  origin?: string
}

txid 是否存在取决于操作结果。

payLightningInvoice

client.payLightningInvoice(params)
// Promise<PayLightningInvoiceResponse>

参数

interface PayLightningInvoiceRequest {
  invoice: string
  amount_msat?: string
  channel_id?: string
  fire_and_forget?: boolean
  require_rgb_channel?: boolean
}

返回值

interface PayLightningInvoiceResponse {
  payment_id: string
  preimage: string
  amount_sats: string
  destination: string
  fee_paid_msat?: string
}

amount_msat、fee_paid_msat：毫聪字符串。
amount_sats：聪字符串。

钱包按发票和支付规则校验参数，不能把网页传入的金额视为权威报价。

卖出发票与原生兑换

generateSellInvoice

client.generateSellInvoice(params)
// Promise<{ invoice: string; payment_hash: string }>

参数

interface GenerateSellInvoiceRequest {
  amount_sats: number
  description?: string
  expiry_secs?: number
  token_amount?: string
  token_ticker?: string
  fee_sats?: number
  total_revenue_sats?: number
}

amount_sats、fee_sats、total_revenue_sats：单位为聪。
expiry_secs：单位为秒。

交易服务必须自行获取权威报价并验证条件。SDK 参数不能替代后端定价、滑点校验或结算核验。

acceptNativeSwap

client.acceptNativeSwap({ swap_string })
// Promise<void>

参数：swap_string 为兑换字符串。无返回值不能当作已结算证明。

节点与 Hub

getNodeInfo

client.getNodeInfo()
// Promise<NodeInfo>

返回值

interface NodeInfo {
  node_base_url: string
  node_id: string
  network: Network
  peer_address?: string
  stash_wallet_id?: string
}

getHubChannels

client.getHubChannels(params?)
// Promise<HubChannelInfo[]>

参数

interface HubChannelsRequest {
  hub_node_id?: string
  include_pending?: boolean
}

返回类型：HubChannelInfo

interface HubChannelInfo {
  channel_id: string
  user_channel_id?: string
  counterparty_node_id: string
  outbound_capacity_sats: number
  inbound_capacity_sats: number
  is_usable: boolean
  is_rgb: boolean
  rgb_contract_id?: string
}

节点凭据与授权

requestNodeCredential

返回加密凭据包，不是明文 token。

client.requestNodeCredential(params)
// Promise<NodeCredentialResponse>

参数与返回值

interface NodeCredentialRequest {
  recipient_pubkey: string
  expiry_seconds?: number
}

interface NodeCredentialResponse {
  encrypted_credential: string
  signature: string
  auth_pubkey: string
}

接收方公钥必须来自可信服务配置，禁止在网页日志中暴露凭据或加密包。

requestNodeGrantSignature

当前公开 grant 类型限定为 regtest。

client.requestNodeGrantSignature(params)
// Promise<NodeGrantSignatureResponse>

参数：NodeGrantSignatureRequest

interface NodeGrantSignatureRequest {
  node_id: string
  apis: string[]
  client_public_key: string
  expires_at: string
  api_risks?: Record<string, 'read' | 'write' | 'funds' | 'control'>
  rules?: Record<string, unknown>
  challenge: {
    challenge_id: string
    nonce: string
    timestamp: number
    expires_at: number
    wallet_type: 'stashwallet'
    network: 'regtest'
    origin: string
    purpose: 'grant'
    wallet_key: string
    user_id: string
  }
}

返回值

interface NodeGrantSignatureResponse {
  grant_signature: string
  grantor_public_key: string
  wallet_type: 'stashwallet'
  network: 'regtest'
  challenge_id: string
}

顶层 expires_at 是字符串，challenge 时间字段是数字，不能混用。challenge 必须由授权服务签发和校验，不能由网页自行构造可信权限。

LSP 委托

requestLspDelegation

先检查 canLsp，并处理运行时拒绝。

client.requestLspDelegation(params)
// Promise<LspDelegationResponse>

参数

interface LspDelegationRequest {
  platform_pubkey?: string
  recipient_pubkey?: string
  platform?: string
  service_name?: string
  expiry_hours?: number
  registration?: LspDelegationRegistrationParams
}

platform_pubkey、platform：可信平台公钥和展示名称。
recipient_pubkey、service_name：兼容别名；缺失时 SDK 分别使用 platform_pubkey、platform 补齐。不要传入冲突值。
expiry_hours：单位为小时。

可选注册参数：LspDelegationRegistrationParams

interface LspDelegationRegistrationParams {
  token_ticker?: string
  custom_fee_rate_percent?: number | string
  channel_hourly_fee_sats?: number
  p_ceiling?: number | string
  p_floor?: number | string
  swap_fee_lsp_percent?: number | string
  swap_fee_platform_percent?: number | string
  channel_fee_lsp_percent?: number | string
  channel_fee_platform_percent?: number | string
}

返回值

interface LspDelegationResponse {
  encrypted_package: string
  signature: string
  signer_pubkey: string
}

requestLspRevoke

client.requestLspRevoke(platform)
// Promise<{ success: boolean }>

参数：platform 为平台名称字符串。

SDK API 参考 ​

客户端创建 ​

创建客户端（推荐） ​

使用构造函数创建客户端 ​

检查扩展是否已检测到 ​

连接与账户 ​

connect ​

disconnect ​

getAccounts ​

getBtcAddress ​

会话、网络与能力 ​

getWalletSessionStatus ​

getNetwork ​

switchNetwork ​

getVersion ​

getCapabilities ​

身份与消息签名 ​

requestAuthSignature ​

signMessage ​

RGB 资产查询 ​

getRgbUtxos ​

getContractBalance ​

isContractKnown ​

合约导入与发行 ​

importContract ​

autoImportContract ​

issueContract ​

比特币、RGB 与闪电支付 ​

sendBitcoin ​

sendRGB ​

payLightningInvoice ​

卖出发票与原生兑换 ​

generateSellInvoice ​

acceptNativeSwap ​

节点与 Hub ​

getNodeInfo ​

getHubChannels ​

节点凭据与授权 ​

requestNodeCredential ​

requestNodeGrantSignature ​

LSP 委托 ​

requestLspDelegation ​

requestLspRevoke ​

SDK API 参考

客户端创建

创建客户端（推荐）

使用构造函数创建客户端

检查扩展是否已检测到

连接与账户

connect

disconnect

getAccounts

getBtcAddress

会话、网络与能力

getWalletSessionStatus

getNetwork

switchNetwork

getVersion

getCapabilities

身份与消息签名

requestAuthSignature

signMessage

RGB 资产查询

getRgbUtxos

getContractBalance

isContractKnown

合约导入与发行

importContract

autoImportContract

issueContract

比特币、RGB 与闪电支付

sendBitcoin

sendRGB

payLightningInvoice

卖出发票与原生兑换

generateSellInvoice

acceptNativeSwap

节点与 Hub

getNodeInfo

getHubChannels

节点凭据与授权

requestNodeCredential

requestNodeGrantSignature

LSP 委托

requestLspDelegation

requestLspRevoke