SDK API reference

Find StashWalletClient methods by function. Calls, parameters, and results are separated; longer type definitions are expandable.

Conventions

All request methods return promises and reject on failure. Result types describe the SDK contract, not guaranteed wallet support. Runtime capabilities, wallet validation, and user approval apply.

Client creation

Create a client (recommended)

For web integrations, use StashWalletClient.connect() to create a client. It waits for the wallet extension to inject its provider into the page, avoiding initialization failures when the page loads before the provider is ready.

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

const client = await StashWalletClient.connect()

Parameters and return value

• timeoutMs: optional provider wait timeout in milliseconds, default 5000. When supplied, it also sets the timeout for subsequent wallet requests.
• Returns Promise<StashWalletClient>. Once resolved, use the client to call wallet methods.

Creating a client does not request site authorization. To connect the user's wallet, call connect() on the client instance:

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

If the wallet extension cannot be detected, client creation fails with PROVIDER_NOT_FOUND. Prompt the user to install or enable the Stash Wallet extension, then reload the page and try again.

Create a client with the constructor

If the wallet provider is already available on the page, you can create a client directly:

const client = new StashWalletClient()

The constructor does not wait for provider injection. The SDK checks for the page provider first, then tries Chrome extension communication. If neither is available, it throws PROVIDER_NOT_FOUND.

To customize communication, pass a Transport instance using the optional transport parameter. See Provider and events for configuration examples.

Check whether the extension is detected

isInstalled() reports whether the SDK detects a wallet provider or extension marker. Use it to control installation hints on the page.

const detected = client.isInstalled()

Returns a boolean. A value of true only means the extension is detected, not that the wallet is unlocked or the user has authorized the site. This method requires an existing client instance. For initial setup, use StashWalletClient.connect() as shown above and handle creation failures.

Connection and accounts

connect

Request user approval for site access.

client.connect()
// Promise<ConnectResult>

Result

interface ConnectResult {
  address: string
}

disconnect

Revoke the current origin's authorization without locking the entire wallet.

client.disconnect()
// Promise<boolean>

getAccounts

Returns an object, not an account array.

client.getAccounts()
// Promise<AccountsResult>

Result

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

getBtcAddress

client.getBtcAddress()
// Promise<BtcAddressResponse>

Result

interface BtcAddressResponse {
  address: string
  network: Network
}

Session, network, and capabilities

getWalletSessionStatus

client.getWalletSessionStatus()
// Promise<WalletSessionStatus>

Result

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

getNetwork

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

Network type

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

Query supportedNetworks for actual support rather than relying on the type alone.

switchNetwork

May require approval or waiting for the switch. Refresh state and capabilities afterward.

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

Parameter: network is the target Network.

getVersion

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

getCapabilities

Query current runtime capabilities.

client.getCapabilities()
// Promise<ProviderCapabilities>

Result type: 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[]
}

Identity and message signing

requestAuthSignature

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

Parameter: AuthSignatureRequest, explicitly specifying version 1 or 2. See Auth login for full requests, responses, and verification.

signMessage

General message signing, not a substitute for the Auth challenge protocol.

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

Parameters and result

interface SignMessageRequest {
  message: string
  origin?: string
}

interface SignMessageResult {
  pubkey: string
  sign: string
}

Origin validation

The origin parameter cannot impersonate another site. The extension determines the actual origin from browser sender metadata.

RGB asset queries

getRgbUtxos

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

Result type: 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>

Parameter: contract_id is a contract ID string.

Result

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

Amount precision

Do not convert amount strings into potentially imprecise JavaScript numbers. Apply asset precision when displaying values.

isContractKnown

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

Parameter: contract_id is a contract ID string.

Result

interface ContractKnownResult {
  contract_id: string
  known: boolean
}

Contract import and issuance

importContract

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

Parameters

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

autoImportContract

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

Parameter: contract_id is a contract ID string.

issueContract

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

Parameters

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

Supply and precision must pass wallet validation. Do not exceed the safe integer range. An exposed method does not guarantee issuance support.

Bitcoin, RGB, and Lightning payments

Fund operations

Page confirmation is not wallet authorization. Timeout does not cancel payment. Check authoritative transaction/payment status before retrying. Avoid logging credentials or unnecessary payment preimages.

sendBitcoin

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

Parameters

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

• satoshis: sat, not BTC.
• feeRate: the SDK type does not specify a unit or default. Confirm against the target wallet version.

sendRGB

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

Parameters

interface SendRGBRequest {
  invoice: string
  origin?: string
}

The presence of txid depends on the result.

payLightningInvoice

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

Parameters

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

Result

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

• amount_msat, fee_paid_msat: millisatoshi strings.
• amount_sats: satoshi string.

The wallet validates invoice/payment rules. Page-supplied amounts are not authoritative quotes.

Sell invoices and native swaps

generateSellInvoice

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

Parameters

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: satoshis.
• expiry_secs: seconds.

Trading services must obtain authoritative quotes and verify conditions independently. SDK parameters do not replace pricing, slippage checks, or settlement verification.

acceptNativeSwap

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

Parameter: swap_string is a swap string. An empty return value is not settlement proof.

Nodes and Hub channels

getNodeInfo

client.getNodeInfo()
// Promise<NodeInfo>

Result

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

getHubChannels

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

Parameters

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

Result type: 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
}

Node credentials and grants

requestNodeCredential

Returns an encrypted package, not a plaintext token.

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

Parameters and result

interface NodeCredentialRequest {
  recipient_pubkey: string
  expiry_seconds?: number
}

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

Obtain the recipient key from trusted service configuration. Do not expose credentials or packages in page logs.

requestNodeGrantSignature

The public grant type currently restricts the network to regtest.

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

Parameters: 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
  }
}

Result

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

Top-level expires_at is a string; challenge timestamps are numbers. Do not interchange them. The authorization service must issue and validate challenges; page-generated values cannot establish trusted permissions.

LSP delegation

requestLspDelegation

Check canLsp first and handle runtime rejection.

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

Parameters

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

• platform_pubkey, platform: trusted platform key and display label.
• recipient_pubkey, service_name: legacy aliases, filled from the corresponding new fields when missing. Do not provide conflicting values.
• expiry_hours: hours.

Optional registration: 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
}

Result

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

requestLspRevoke

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

Parameter: platform is a platform name string.