🤖gRPC API

This page was automatically generated.

Paths for the REST proxy of the gRPC interface can be found here.

boltzrpc.Boltz

Methods

GetInfo

Gets general information about the daemon like the chain of the lightning node it is connected to and the IDs of pending swaps.

GetServiceInfo

Fetches the latest limits and fees from the Boltz backend API it is connected to.

GetPairInfo

Fetches information about a specific pair for a chain swap.

GetPairs

Fetches all available pairs for submarine and reverse swaps.

ListSwaps

Returns a list of all swaps, reverse swaps, and chain swaps in the database.

GetStats

Returns stats of all swaps, reverse swaps, and chain swaps in the database.

RefundSwap

Refund a failed swap manually. This is only required when no refund address has been set and the swap does not have an associated wallet.

ClaimSwaps

Claim swaps manually. This is only required when no claim address has been set and the swap does not have an associated wallet.

GetSwapInfo

Gets all available information about a swap from the database.

GetSwapInfoStream

Returns the entire history of the swap if is still pending and streams updates in real time. If the swap id is empty or "*" updates for all swaps will be streamed.

Deposit

This is a wrapper for channel creation swaps. The daemon only returns the ID, timeout block height and lockup address. The Boltz backend takes care of the rest. When an amount of onchain coins that is in the limits is sent to the address before the timeout block height, the daemon creates a new lightning invoice, sends it to the Boltz backend which will try to pay it and if that is not possible, create a new channel to make the swap succeed.

CreateSwap

Creates a new swap from onchain to lightning.

CreateChannel

Create a new swap from onchain to a new lightning channel. The daemon will only accept the invoice payment if the HTLCs is coming trough a new channel channel opened by Boltz.

CreateReverseSwap

Creates a new reverse swap from lightning to onchain. If accept_zero_conf is set to true in the request, the daemon will not wait until the lockup transaction from Boltz is confirmed in a block, but will claim it instantly.

CreateChainSwap

Creates a new chain swap from one chain to another. If accept_zero_conf is set to true in the request, the daemon will not wait until the lockup transaction from Boltz is confirmed in a block, but will claim it instantly.

CreateWallet

Creates a new liquid wallet and returns the mnemonic.

ImportWallet

Imports an existing wallet.

SetSubaccount

Sets the subaccount of a wallet. Not supported for readonly wallets.

GetSubaccounts

Returns all subaccounts for a given wallet. Not supported for readonly wallets.

GetWallets

Returns all available wallets.

GetWallet

Returns the current balance and subaccount of a wallet.

RequestResponse

GetWalletSendFee

Calculates the fee for an equivalent WalletSend request. If address is left empty, a dummy swap address will be used, allowing for a fee estimation of a swap lockup transaction.

ListWalletTransactions

Returns recent transactions from a wallet.

GetWalletCredentials

Returns the credentials of a wallet. The password will be required if the wallet is encrypted.

RemoveWallet

Removes a wallet.

WalletSend

Send coins from a wallet. Only the confirmed balance can be spent.

WalletReceive

Get a new address of the wallet.

Stop

Gracefully stops the daemon.

Unlock

Unlocks the server. This will be required on startup if there are any encrypted wallets.

VerifyWalletPassword

Check if the password is correct.

ChangeWalletPassword

Changes the password for wallet encryption.

CreateTenant

Creates a new tenant which can be used to bake restricted macaroons.

ListTenants

Returns all tenants.

GetTenant

Get a specifiy tenant.

RequestResponse

BakeMacaroon

Bakes a new macaroon with the specified permissions. The macaroon can also be restricted to a specific tenant. In this case, - any swap or wallet created with the returned macaroon will belong to this tenant and can not be accessed by other tenants. - the lightning node connected to the daemon can not be used to pay or create invoices for swaps.

Messages

AnySwapInfo

FieldTypeLabelDescription

id

type

pair

state

error

optional

status

from_amount

The expected amount to be sent to the lockup address for submarine and chain swaps and the invoice amount for reverse swaps.

to_amount

from_amount minus the service and network fee.

created_at

service_fee

optional

onchain_fee

optional

inclues the routing fee for reverse swaps

is_auto

tenant_id

BakeMacaroonRequest

FieldTypeLabelDescription

tenant_id

optional

permissions

repeated

BakeMacaroonResponse

FieldTypeLabelDescription

macaroon

Balance

FieldTypeLabelDescription

total

confirmed

unconfirmed

BlockHeights

FieldTypeLabelDescription

btc

liquid

optional

Budget

FieldTypeLabelDescription

total

remaining

start_date

end_date

ChainSwapData

FieldTypeLabelDescription

id

currency

private_key

their_public_key

amount

timeout_block_height

lockup_transaction_id

optional

transaction_id

optional

wallet_id

optional

address

optional

blinding_key

optional

lockup_address

ChainSwapInfo

FieldTypeLabelDescription

id

pair

state

error

status

preimage

is_auto

service_fee

optional

service_fee_percent

onchain_fee

optional

created_at

tenant_id

from_data

to_data

ChangeWalletPasswordRequest

FieldTypeLabelDescription

old

new

ChannelCreationInfo

Channel creations are an optional extension to a submarine swap in the data types of boltz-client.

FieldTypeLabelDescription

swap_id

ID of the swap to which this channel channel belongs

status

inbound_liquidity

private

funding_transaction_id

funding_transaction_vout

ChannelId

FieldTypeLabelDescription

cln

cln style: 832347x2473x1

lnd

lnd style: 915175205006540801

ClaimSwapsRequest

FieldTypeLabelDescription

swap_ids

repeated

address

wallet_id

ClaimSwapsResponse

FieldTypeLabelDescription

transaction_id

CombinedChannelSwapInfo

FieldTypeLabelDescription

swap

channel_creation

CreateChainSwapRequest

FieldTypeLabelDescription

amount

optional

Amount of satoshis to swap. It is the amount expected to be sent to the lockup address. If left empty, any amount within the limits will be accepted.

pair

to_address

optional

Address where funds will be swept to if the swap succeeds

refund_address

optional

Address where the coins should be refunded to if the swap fails.

from_wallet_id

optional

Wallet from which the swap should be paid from. Ignored if external_pay is set to true. If the swap fails, funds will be refunded to this wallet as well.

to_wallet_id

optional

Wallet where the the funds will go if the swap succeeds.

accept_zero_conf

optional

Whether the daemon should broadcast the claim transaction immediately after the lockup transaction is in the mempool. Should only be used for smaller amounts as it involves trust in Boltz.

external_pay

optional

If set, the daemon will not pay the swap from an internal wallet.

lockup_zero_conf

optional

Boltz does not accept 0-conf for Liquid transactions with a fee of 0.01 sat/vByte; when lockup_zero_conf is enabled, a fee of 0.1 sat/vByte will be used for Liquid lockup transactions

sat_per_vbyte

optional

Fee rate to use when sending from internal wallet

accepted_pair

optional

Rates to accept for the swap. Queries latest from boltz otherwise The recommended way to use this is to pass a user approved value from a previous GetPairInfo call

CreateChannelRequest

FieldTypeLabelDescription

amount

inbound_liquidity

Percentage of inbound liquidity the channel that is opened should have. 25 by default.

private

CreateReverseSwapRequest

FieldTypeLabelDescription

amount

amount of satoshis to swap

address

If no value is set, the daemon will query a new address from the lightning node

accept_zero_conf

Whether the daemon should broadcast the claim transaction immediately after the lockup transaction is in the mempool. Should only be used for smaller amounts as it involves trust in boltz.

pair

chan_ids

repeated

a list of channel ids which are allowed for paying the invoice. can be in either cln or lnd style.

wallet_id

optional

wallet from which the onchain address should be generated - only considered if address is not set

return_immediately

optional

Whether the daemon should return immediately after creating the swap or wait until the swap is successful or failed. It will always return immediately if accept_zero_conf is not set.

external_pay

optional

If set, the daemon will not pay the invoice of the swap and return the invoice to be paid. This implicitly sets return_immediately to true.

description

optional

Description of the invoice which will be created for the swap

description_hash

optional

Description hash of the invoice which will be created for the swap. Takes precedence over description

invoice_expiry

optional

Expiry of the reverse swap invoice in seconds

accepted_pair

optional

Rates to accept for the swap. Queries latest from boltz otherwise The recommended way to use this is to pass a user approved value from a previous GetPairInfo call

CreateReverseSwapResponse

FieldTypeLabelDescription

id

lockup_address

routing_fee_milli_sat

optional

Only populated when zero-conf is accepted and return_immediately is set to false

claim_transaction_id

optional

Only populated when zero-conf is accepted and return_immediately is set to false

invoice

optional

Invoice to be paid. Only populated when external_pay is set to true

CreateSwapRequest

FieldTypeLabelDescription

amount

pair

not yet supported repeated string chan_ids = 3;

send_from_internal

the daemon will pay the swap using the onchain wallet specified in the wallet field or any wallet otherwise.

refund_address

optional

address where the coins should go if the swap fails. Refunds will go to any of the daemons wallets otherwise.

wallet_id

optional

wallet to pay swap from. only used if send_from_internal is set to true

invoice

optional

bolt11 invoice, lnurl, or lnaddress to use for the swap. required in standalone mode. when connected to a lightning node, a new invoice for amount sats will be fetched the amount field has to be populated in case of a lnurl and lnaddress

zero_conf

optional

Boltz does not accept 0-conf for Liquid transactions with a fee of 0.01 sat/vByte; when zero_conf is enabled, a fee of 0.1 sat/vByte will be used for Liquid lockup transactions

sat_per_vbyte

optional

Fee rate to use when sending from internal wallet

accepted_pair

optional

Rates to accept for the swap. Queries latest from boltz otherwise The recommended way to use this is to pass a user approved value from a previous GetPairInfo call

CreateSwapResponse

FieldTypeLabelDescription

id

address

expected_amount

bip21

tx_id

lockup transaction id. Only populated when send_from_internal was specified in the request

timeout_block_height

timeout_hours

CreateTenantRequest

FieldTypeLabelDescription

name

CreateWalletRequest

FieldTypeLabelDescription

params

CreateWalletResponse

FieldTypeLabelDescription

mnemonic

wallet

DepositRequest

FieldTypeLabelDescription

inbound_liquidity

Percentage of inbound liquidity the channel that is opened in case the invoice cannot be paid should have. 25 by default.

DepositResponse

FieldTypeLabelDescription

id

address

timeout_block_height

Fees

FieldTypeLabelDescription

percentage

miner

GetInfoRequest

GetInfoResponse

FieldTypeLabelDescription

version

node

network

node_pubkey

auto_swap_status

one of: running, disabled, error

block_heights

mapping of the currency to the latest block height.

refundable_swaps

repeated

swaps that need a manual interaction to refund

tenant

optional

the currently authenticated tenant

claimable_swaps

repeated

swaps that need a manual interaction to claim

symbol

Deprecated.

lnd_pubkey

Deprecated.

block_height

Deprecated.

pending_swaps

repeated

Deprecated.

pending_reverse_swaps

repeated

Deprecated.

GetPairInfoRequest

FieldTypeLabelDescription

type

pair

GetPairsResponse

FieldTypeLabelDescription

submarine

repeated

reverse

repeated

chain

repeated

GetServiceInfoRequest

GetServiceInfoResponse

FieldTypeLabelDescription

fees

limits

GetStatsRequest

FieldTypeLabelDescription

include

GetStatsResponse

FieldTypeLabelDescription

stats

GetSubaccountsRequest

FieldTypeLabelDescription

wallet_id

GetSubaccountsResponse

FieldTypeLabelDescription

current

optional

subaccounts

repeated

GetSwapInfoRequest

FieldTypeLabelDescription

id

GetSwapInfoResponse

FieldTypeLabelDescription

swap

channel_creation

reverse_swap

chain_swap

GetTenantRequest

FieldTypeLabelDescription

name

GetWalletCredentialsRequest

FieldTypeLabelDescription

id

password

optional

GetWalletRequest

FieldTypeLabelDescription

name

optional

id

optional

GetWalletsRequest

FieldTypeLabelDescription

currency

optional

include_readonly

optional

ImportWalletRequest

FieldTypeLabelDescription

credentials

params

ImportWalletResponse

LightningChannel

FieldTypeLabelDescription

id

capacity

outbound_sat

inbound_sat

peer_id

Limits

FieldTypeLabelDescription

minimal

maximal

maximal_zero_conf_amount

ListSwapsRequest

FieldTypeLabelDescription

from

optional

to

optional

state

optional

include

limit

optional

offset

optional

unify

optional

wether to return swaps in the shared all_swaps list or in the detailed lists. the limit and offset are only considered when unify is true.

ListSwapsResponse

FieldTypeLabelDescription

swaps

repeated

channel_creations

repeated

Deprecated.

reverse_swaps

repeated

chain_swaps

repeated

all_swaps

repeated

populated when unify is set to true in the request

ListTenantsRequest

ListTenantsResponse

FieldTypeLabelDescription

tenants

repeated

ListWalletTransactionsRequest

FieldTypeLabelDescription

id

exclude_swap_related

optional

limit

optional

offset

optional

ListWalletTransactionsResponse

FieldTypeLabelDescription

transactions

repeated

MacaroonPermissions

FieldTypeLabelDescription

action

MinerFees

FieldTypeLabelDescription

normal

reverse

Pair

FieldTypeLabelDescription

from

to

PairInfo

FieldTypeLabelDescription

pair

fees

limits

hash

RefundSwapRequest

FieldTypeLabelDescription

id

address

wallet_id

RemoveWalletRequest

FieldTypeLabelDescription

id

RemoveWalletResponse

ReverseSwapInfo

FieldTypeLabelDescription

id

state

error

status

Latest status message of the Boltz backend

private_key

preimage

redeem_script

invoice

claim_address

onchain_amount

invoice_amount

timeout_block_height

lockup_transaction_id

claim_transaction_id

pair

chan_ids

repeated

blinding_key

optional

created_at

paid_at

optional

the time when the invoice was paid

service_fee

optional

onchain_fee

optional

routing_fee_msat

optional

external_pay

tenant_id

is_auto

SetSubaccountRequest

FieldTypeLabelDescription

wallet_id

subaccount

optional

The subaccount to use. If not set, a new one will be created.

Subaccount

FieldTypeLabelDescription

balance

pointer

type

descriptors

repeated

SwapFees

FieldTypeLabelDescription

percentage

miner_fees

SwapInfo

FieldTypeLabelDescription

id

pair

state

error

status

Latest status message of the Boltz backend

private_key

preimage

redeem_script

invoice

lockup_address

expected_amount

timeout_block_height

lockup_transaction_id

refund_transaction_id

If the swap times out or fails for some other reason, the damon will automatically refund the coins sent to the lockup_address back to the configured wallet or the address specified in the refund_address field.

refund_address

optional

chan_ids

repeated

blinding_key

optional

created_at

service_fee

optional

onchain_fee

optional

wallet_id

optional

internal wallet which was used to pay the swap

tenant_id

is_auto

SwapStats

FieldTypeLabelDescription

total_fees

total_amount

avg_fees

avg_amount

count

success_count

Tenant

FieldTypeLabelDescription

id

name

TransactionInfo

FieldTypeLabelDescription

swap_id

optional

will be populated for LOCKUP, REFUND and CLAIM

type

TransactionOutput

FieldTypeLabelDescription

address

amount

is_our_address

wether the address is controlled by the wallet

UnlockRequest

FieldTypeLabelDescription

password

VerifyWalletPasswordRequest

FieldTypeLabelDescription

password

VerifyWalletPasswordResponse

FieldTypeLabelDescription

correct

Wallet

FieldTypeLabelDescription

id

name

currency

readonly

balance

tenant_id

WalletCredentials

FieldTypeLabelDescription

mnemonic

optional

only one of these is allowed to be present

xpub

optional

core_descriptor

optional

subaccount

optional

only used in combination with mnemonic

WalletParams

FieldTypeLabelDescription

name

currency

password

optional

the password to encrypt the wallet with. If there are existing encrypted wallets, the same password has to be used.

WalletReceiveRequest

FieldTypeLabelDescription

id

WalletReceiveResponse

FieldTypeLabelDescription

address

WalletSendFee

FieldTypeLabelDescription

amount

amount of sats which would be sent

fee

fee_rate

the fee rate used for the estimation in sat/vbyte

WalletSendRequest

FieldTypeLabelDescription

id

address

amount

Amount of satoshis to be sent to 'address`

sat_per_vbyte

optional

Fee rate to use for the transaction

send_all

optional

Sends all available funds to the address. The amount field is ignored.

is_swap_address

optional

whether address is the lockup of a swap.

WalletSendResponse

FieldTypeLabelDescription

tx_id

WalletTransaction

FieldTypeLabelDescription

id

balance_change

balance change of the wallet in satoshis. its the sum of all output values minus the sum of all input values which are controlled by the wallet. positive values indicate incoming transactions, negative values outgoing transactions

timestamp

outputs

repeated

block_height

infos

repeated

additional informations about the tx (type, related swaps etc.)

Wallets

FieldTypeLabelDescription

wallets

repeated

Enums

Currency

NameNumberDescription

BTC

0

LBTC

1

IncludeSwaps

NameNumberDescription

ALL

0

MANUAL

1

AUTO

2

MacaroonAction

NameNumberDescription

READ

0

WRITE

1

SwapState

NameNumberDescription

PENDING

0

SUCCESSFUL

1

ERROR

2

Unknown client error. Check the error field of the message for more information

SERVER_ERROR

3

Unknown server error. Check the status field of the message for more information

REFUNDED

4

Client refunded locked coins after the HTLC timed out

ABANDONED

5

Client noticed that the HTLC timed out but didn't find any outputs to refund

SwapType

NameNumberDescription

SUBMARINE

0

REVERSE

1

CHAIN

2

TransactionType

NameNumberDescription