This document covers UniSat’s WebRGB v1 provider at window.rgb. It is a
standards-oriented adapter for common RGB receive, send, and tracking flows.
It is separate from UniSat’s native API:
| Provider | Purpose | Amount representation |
|---|---|---|
window.rgb |
WebRGB v1 interoperability | Safe integers; burn uses a u64 string |
window.unisat.rgb |
UniSat-specific issuance, payments, and RGB/BTC swaps | Unsigned decimal strings |
For the native API, see Native RGB API. Methods from the two providers are not interchangeable. In particular, WebRGB does not expose the native swap workflow or UniSat’s order-based NIA issuance workflow.
UniSat installs window.rgb only when that slot is not already owned by
another wallet. It always participates in multi-wallet discovery:
rgb:requestProvider;rgb:announceProvider with { info, provider };window.rgb, it also dispatches rgb:ready with
{ version: '1.0.0' }.const announced: Array<{ info: any; provider: any }> = []
window.addEventListener('rgb:announceProvider', event => {
announced.push((event as CustomEvent).detail)
})
window.dispatchEvent(new Event('rgb:requestProvider'))
UniSat announces:
{
name: 'UniSat Wallet',
rdns: 'io.unisat.wallet',
uuid: '<fresh UUID for this page load>',
}
Deduplicate providers by rdns, not by uuid. The UUID identifies one page
announcement and changes on reload.
Call enable() before every other WebRGB method:
const rgb = window.rgb
if (!rgb) throw new Error('No WebRGB provider found')
await rgb.enable()
const info = await rgb.getInfo()
enable() uses UniSat’s normal site-connection approval and is idempotent for
an already connected origin. If the wallet is locked, the request first opens
the wallet unlock flow. A later account-bound call also reopens the unlock flow
when necessary.
provider.enabled only means that enable() completed in the current page.
Use getInfo().ready to decide whether the selected wallet and chain can use
RGB:
type RgbInfo = {
ready: boolean
network: string
protocol: 'RGB_L1' | null
methods: string[]
burnRecipientNamespaces?: string[]
proxyProfiles?: Array<{
id: string
name: string
endpoint: string
protocolVersion?: string
serverVersion?: string
recommended: boolean
}>
defaultProxyId?: string
}
When RGB is unavailable, UniSat returns ready: false, protocol: null, and
only advertises enable and getInfo. Check methods before calling an
optional method. If site permission is removed, the next call rejects with
NOT_ENABLED; call enable() again instead of retrying the failed operation.
On an RGB-enabled L1 wallet, getInfo().methods contains:
| Method | Action approval | Purpose |
|---|---|---|
enable |
Connection only | Connect the current origin. |
getInfo |
No | Return readiness and capabilities. |
getAddress |
No | Return the Bitcoin address anchoring RGB state. |
blindReceive |
Yes | Create a one-time blinded receive invoice. |
witnessReceive |
Yes | Create a receive invoice whose output is created by the sender transaction. |
listAssets |
No | Return all locally known RGB assets. |
getAssetBalance |
No | Return one asset balance. |
sendAsset |
Yes | Prepare, sign, deliver, ACK, and broadcast an RGB payment. |
burnAsset |
Yes | Burn a BFA asset to an approved bridge destination. |
getConsignment |
Yes | Share a saved BFA burn proof with the requesting site. |
listTransfers |
No | Return local send/receive history. |
getTransferStatus |
No | Find one transfer by wallet ID, recipient ID, or txid. |
decodeRgbInvoice |
No | Decode an invoice without moving funds. |
on / off |
No | Subscribe to polled transfer events. |
Read methods do not open an action-confirmation screen, although connection or wallet unlock may still be required.
The following WebRGB methods are present on the JavaScript object for
compatibility but are not advertised and reject with METHOD_NOT_SUPPORTED:
issueAssetsignMessagemakeLnInvoicepayLnInvoiceUniSat currently reports RGB_L1, not RGB_LN. Native
window.unisat.rgb.issueNia() support does not make WebRGB issueAsset
available because the native flow requires a verified order ID and service-fee
payment that WebRGB’s arguments cannot represent.
Most WebRGB fungible amounts are JavaScript number values and must be safe
integers:
Number.isSafeInteger(amount) && amount > 0
They are atomic/base units; apply the asset’s precision only for display.
UniSat rejects values above Number.MAX_SAFE_INTEGER rather than rounding
them. This differs from the native API, which accepts decimal strings and can
represent the full protocol range.
burnAsset.amount is the intentional exception: it is a positive decimal
string up to 18446744073709551615 (u64::MAX). This lets a dApp burn the
full protocol range without JavaScript number rounding.
feeRate, durationSeconds, and minConfirmations are also numeric. Do not
pass decimal strings to WebRGB methods unless a future advertised capability
explicitly allows them.
getInfo()Returns the readiness object described above and refreshes the capability list
for the current wallet context. When ready is true, it also returns the
wallet’s selectable, trusted proxyProfiles and the effective
defaultProxyId.
const info = await rgb.getInfo()
for (const profile of info.proxyProfiles ?? []) {
console.log(
profile.id,
profile.name,
profile.protocolVersion,
profile.serverVersion,
profile.recommended
)
}
protocolVersion is the Proxy JSON-RPC protocol version; serverVersion is
the Proxy server implementation version. They are independent—for example,
protocol 1.0 can be exposed by server 0.3.0 or 0.4.0. These fields help a
dApp present compatibility choices, while the wallet still verifies the Proxy
at runtime. Profiles that are not selectable are not returned.
Do not construct a profile or derive a proxyId from an endpoint. Pass back
only an id returned by the current wallet context. Profile availability can
change with the selected account, chain, or wallet configuration, so refresh
getInfo() before presenting a long-lived Proxy selector.
getAddress()const { address } = await rgb.getAddress()
The address is the wallet’s Bitcoin RGB funding address. It is not an RGB
invoice and must not be passed to sendAsset as a recipient ID.
blindReceive(args?) and witnessReceive(args?)const receive = await rgb.blindReceive({
assetId: 'rgb:...', // omit for any asset
amount: 1000, // omit for any amount
durationSeconds: 900,
minConfirmations: 3,
proxyId: 'signet-v04', // optional ID from getInfo().proxyProfiles
})
// {
// invoice,
// recipientId,
// expirationTimestamp,
// minConfirmations,
// }
Rules:
assetId, when supplied, must identify an asset already known to the wallet;
otherwise the call rejects with ASSET_NOT_FOUND.amount must be a positive safe integer and requires assetId.durationSeconds must be a positive integer. The wallet’s default is 24
hours when it is omitted.minConfirmations must be a nonnegative integer. UniSat raises it to a
minimum of three and returns the effective value.proxyId, when supplied, must be the ID of a selectable profile advertised
by getInfo().proxyProfiles. Omit it to use defaultProxyId.Use blindReceive when an available RGB funding UTXO can be reserved. Use
witnessReceive when the sender transaction should create the receiver output.
Both calls persist receiver state before returning the invoice and open the
wallet’s receive approval screen. Before approval, UniSat resolves the trusted
profile and pins the default when proxyId was omitted. Invoice Details show
the selected Proxy name, ID, protocol version, server version, and endpoint;
page-supplied profile metadata is ignored.
listAssets()Returns a plain array, loading up to 50 items per internal page:
const assets = await rgb.listAssets()
// [{ assetId, id, asset_id, ticker, name, precision, balance, ... }]
assetId, id, and asset_id refer to the same contract. Additional fields
are wallet metadata and may evolve; use the named identifiers and precision
rather than depending on the raw object shape.
getAssetBalance(assetId)const result = await rgb.getAssetBalance('rgb:...')
// { assetId, balance: 1000, raw: { ... } }
balance is a safe integer in atomic units. A balance outside the WebRGB
number range is rejected instead of being returned lossily. raw is the
wallet’s underlying asset record and is not a portable WebRGB contract.
decodeRgbInvoice(invoice)Both forms are accepted:
await rgb.decodeRgbInvoice(invoice)
await rgb.decodeRgbInvoice({ invoice })
The result is:
{
assetId?: string
amount: number | null
recipientId: string
expirationTimestamp?: number
network?: string
transportEndpoints: string[]
}
amount: null means an any-amount invoice, including an invoice encoding a
fungible assignment of zero. Decoding is local and read-only; it does not
reserve assets, contact a proxy, or show an approval.
sendAsset(args)The invoice form is preferred:
const result = await rgb.sendAsset({
invoice,
// Required when the invoice does not fix these values:
amount: 1000,
assetId: 'rgb:...',
feeRate: 5,
})
The explicit recipient form is also supported:
const result = await rgb.sendAsset({
assetId: 'rgb:...',
amount: 1000,
recipientId: 'bc:utxob:...',
feeRate: 5,
// transportEndpoints: ['rpcs://proxy.example'],
})
For the invoice form:
amount;assetId, unless the wallet holds exactly one
asset and UniSat can select it unambiguously;For the explicit form, UniSat builds and validates an invoice using the supplied recipient and either the supplied proxy endpoints or the current chain defaults.
The call uses the native two-stage payment flow internally, so the user sees the normal payment review followed by signing approval. Consent for any untrusted direct RGB proxy endpoint is merged into the payment review. If the user rejects signing, UniSat releases the unsigned prepared reservation. A counterparty rejection or transport failure is not treated as user rejection; track that transfer instead of blindly creating another one.
The result includes normalized tracking fields:
{
transferId: string | number
txid?: string
assetId: string
amount: number
recipientId?: string
status: 'WaitingCounterparty' | 'WaitingConfirmations' | 'Settled' | 'Failed'
// plus wallet-specific result fields
}
Persist transferId. A send can return before settlement when it is waiting
for the receiver ACK or Bitcoin confirmations.
burnAsset(args)burnAsset is available only for BFA assets. It validates the expected RGB
network, CAIP-2 destination chain and native recipient address before opening
the confirmation flow:
const burn = await rgb.burnAsset({
network: info.network,
assetId: 'rgb:...',
amount: '1000000000000000000',
burnRecipient: {
chainId: 'eip155:42161',
address: '0x...',
},
feeRate: 2,
minConfirmations: 3,
})
Use getInfo().burnRecipientNamespaces to feature-detect destination address
families. UniSat currently returns ['eip155', 'tron']; the concrete chain
must also be one of the wallet’s configured BFA bridge routes. A signing
rejection releases the unsigned RGB allocation reservation.
Current-schema BFA Burn transitions cannot contain a change assignment. If
the wallet does not already have an exact combination of allocations for the
requested amount, burnAsset automatically performs a wallet-owned split
transaction and then prepares the terminal Burn. The user sees two signing
confirmations and pays both Bitcoin transaction fees. The provider resolves
only after the second transaction is broadcast; the intermediate PSBT and
transfer ID are not returned to the dApp.
getConsignment({ assetId, txid })This method exports the exact saved transfer consignment for a completed BFA
burn. It does not export arbitrary transfers and never performs another burn.
UniSat confirms sharing with the user and verifies that assetId and txid
identify the same saved proof.
const proof = await rgb.getConsignment({ assetId: burn.assetId, txid: burn.txid })
// {
// assetId, txid,
// encoding: 'base64',
// data,
// byteLength,
// digest: { algorithm: 'keccak256', value: '0x...' },
// }
listTransfers(assetId?)const all = await rgb.listTransfers()
const oneAsset = await rgb.listTransfers('rgb:...')
Returns a plain array. Transfer amounts are converted to safe integers; an unsafe persisted value rejects rather than being rounded. UniSat normalizes wallet states as follows:
| Wallet state | WebRGB state |
|---|---|
settled, confirmed |
Settled |
failed, rejected, canceled, broadcast_failed |
Failed |
confirming, broadcasted, waiting_receive |
WaitingConfirmations |
waiting_batch_release |
WaitingCounterparty |
| Other pending states | WaitingCounterparty |
getTransferStatus(transferId, assetId?)const status = await rgb.getTransferStatus(transferId, assetId)
The identifier is matched against the wallet transfer ID, recipient ID, txid, or record ID. An unknown identifier resolves rather than rejects:
{ found: false, status: null, transfer: null }
const listener = transfer => console.log(transfer)
rgb.on('transferReceived', listener)
rgb.on('transferSettled', listener)
rgb.off('transferReceived', listener)
rgb.off('transferSettled', listener)
Supported events are:
| Event | Fires when |
|---|---|
transferReceived |
A new incoming transfer appears after the subscription baseline. |
transferSettled |
A known transfer changes to Settled. |
UniSat polls every 15 seconds only while at least one listener is registered.
The first poll establishes a baseline and does not replay historical receives.
Events are convenience notifications; persist transfer IDs and use
getTransferStatus for authoritative recovery after reload.
Every WebRGB rejection is an Error with a string code:
| Code | Meaning |
|---|---|
USER_REJECTED |
The user rejected connection or an action approval. |
NOT_ENABLED |
enable() has not completed, site permission was removed, or RGB is disabled. |
METHOD_NOT_SUPPORTED |
The method is not in getInfo().methods. |
INVALID_PARAMS |
An argument is missing, malformed, mismatched, or outside the safe-number range. |
ASSET_NOT_FOUND |
The wallet does not know the requested asset. |
INTERNAL_ERROR |
Any other wallet, transport, or protocol failure. |
try {
await rgb.sendAsset({ invoice, amount: 1000 })
} catch (error) {
switch ((error as { code?: string }).code) {
case 'USER_REJECTED':
break
case 'NOT_ENABLED':
await rgb.enable()
break
default:
console.error((error as Error).message)
}
}
Do not depend on instanceof, a stack trace, data.originalError, or native
numeric wallet codes. The provider maps errors crossing the extension boundary
to this WebRGB code set and exposes only the safe message needed by the page.
UniSat follows the draft WebRGB v1 specification
and its type declarations,
subject to the capability list returned by getInfo(). When a method is not
advertised, the runtime capability list takes precedence over the broader
upstream interface.