🤖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.

Request	Response
GetInfoRequest	GetInfoResponse

GetServiceInfo

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

Request	Response
GetServiceInfoRequest	GetServiceInfoResponse

GetPairInfo

Fetches information about a specific pair for a chain swap.

Request	Response
GetPairInfoRequest	PairInfo

GetPairs

Fetches all available pairs for submarine and reverse swaps.

Request	Response
.google.protobuf.Empty	GetPairsResponse

ListSwaps

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

Request	Response
ListSwapsRequest	ListSwapsResponse

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.

Request	Response
RefundSwapRequest	GetSwapInfoResponse

ClaimSwaps

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

Request	Response
ClaimSwapsRequest	ClaimSwapsResponse

GetSwapInfo

Gets all available information about a swap from the database.

Request	Response
GetSwapInfoRequest	GetSwapInfoResponse

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.

Request	Response
GetSwapInfoRequest	GetSwapInfoResponse stream

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.

Request	Response
DepositRequest	DepositResponse

CreateSwap

Creates a new swap from onchain to lightning.

Request	Response
CreateSwapRequest	CreateSwapResponse

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.

Request	Response
CreateChannelRequest	CreateSwapResponse

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.

Request	Response
CreateReverseSwapRequest	CreateReverseSwapResponse

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.

Request	Response
CreateChainSwapRequest	ChainSwapInfo

CreateWallet

Creates a new liquid wallet and returns the mnemonic.

Request	Response
CreateWalletRequest	CreateWalletResponse

ImportWallet

Imports an existing wallet.

Request	Response
ImportWalletRequest	Wallet

SetSubaccount

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

Request	Response
SetSubaccountRequest	Subaccount

GetSubaccounts

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

Request	Response
GetSubaccountsRequest	GetSubaccountsResponse

GetWallets

Returns all available wallets.

Request	Response
GetWalletsRequest	Wallets

GetWallet

Returns the current balance and subaccount of a wallet.

Request	Response
GetWalletRequest	Wallet

GetWalletCredentials

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

Request	Response
GetWalletCredentialsRequest	WalletCredentials

RemoveWallet

Removes a wallet.

Request	Response
RemoveWalletRequest	RemoveWalletResponse

Stop

Gracefully stops the daemon.

Request	Response
.google.protobuf.Empty	.google.protobuf.Empty

Unlock

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

Request	Response
UnlockRequest	.google.protobuf.Empty

VerifyWalletPassword

Check if the password is correct.

Request	Response
VerifyWalletPasswordRequest	VerifyWalletPasswordResponse

ChangeWalletPassword

Changes the password for wallet encryption.

Request	Response
ChangeWalletPasswordRequest	.google.protobuf.Empty

CreateTenant

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

Request	Response
CreateTenantRequest	Tenant

ListTenants

Returns all tenants.

Request	Response
ListTenantsRequest	ListTenantsResponse

GetTenant

Get a specifiy tenant.

Request	Response
GetTenantRequest	Tenant

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.

Request	Response
BakeMacaroonRequest	BakeMacaroonResponse

Messages

BakeMacaroonRequest

Field	Type	Label	Description
tenant_id	uint64	optional
permissions	MacaroonPermissions	repeated

BakeMacaroonResponse

Field	Type	Label	Description
macaroon	string

Balance

Field	Type	Label	Description
total	uint64
confirmed	uint64
unconfirmed	uint64

BlockHeights

Field	Type	Label	Description
btc	uint32
liquid	uint32	optional

Budget

Field	Type	Label	Description
total	uint64
remaining	int64
start_date	int64
end_date	int64

ChainSwapData

Field	Type	Label	Description
id	string
currency	Currency
private_key	string
their_public_key	string
amount	uint64
timeout_block_height	uint32
lockup_transaction_id	string	optional
transaction_id	string	optional
wallet_id	uint64	optional
address	string	optional
blinding_key	string	optional
lockup_address	string

ChainSwapInfo

Field	Type	Label	Description
id	string
pair	Pair
state	SwapState
error	string
status	string
preimage	string
is_auto	bool
service_fee	uint64	optional
service_fee_percent	double
onchain_fee	uint64	optional
created_at	int64
tenant_id	uint64
from_data	ChainSwapData
to_data	ChainSwapData

ChangeWalletPasswordRequest

Field	Type	Label	Description
old	string
new	string

ChannelCreationInfo

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

Field	Type	Label	Description
swap_id	string		ID of the swap to which this channel channel belongs
status	string
inbound_liquidity	uint32
private	bool
funding_transaction_id	string
funding_transaction_vout	uint32

ChannelId

Field	Type	Label	Description
cln	string		cln style: 832347x2473x1
lnd	uint64		lnd style: 915175205006540801

ClaimSwapsRequest

Field	Type	Label	Description
swap_ids	string	repeated
address	string
wallet_id	uint64

ClaimSwapsResponse

Field	Type	Label	Description
transaction_id	string

CombinedChannelSwapInfo

Field	Type	Label	Description
swap	SwapInfo
channel_creation	ChannelCreationInfo

CreateChainSwapRequest

Field	Type	Label	Description
amount	uint64		Amount of satoshis to swap. It is the amount expected to be sent to the lockup address.
pair	Pair
to_address	string	optional	Address where funds will be swept to if the swap succeeds
refund_address	string	optional	Address where the coins should be refunded to if the swap fails.
from_wallet_id	uint64	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	uint64	optional	Wallet where the the funds will go if the swap succeeds.
accept_zero_conf	bool	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	bool	optional	If set, the daemon will not pay the swap from an internal wallet.

CreateChannelRequest

Field	Type	Label	Description
amount	int64
inbound_liquidity	uint32		Percentage of inbound liquidity the channel that is opened should have. 25 by default.
private	bool

CreateReverseSwapRequest

Field	Type	Label	Description
amount	uint64		amount of satoshis to swap
address	string		If no value is set, the daemon will query a new address from the lightning node
accept_zero_conf	bool		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	Pair
chan_ids	string	repeated	a list of channel ids which are allowed for paying the invoice. can be in either cln or lnd style.
wallet_id	uint64	optional	wallet from which the onchain address should be generated - only considered if address is not set
return_immediately	bool	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	bool	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	string	optional	Description of the invoice which will be created for the swap

CreateReverseSwapResponse

Field	Type	Label	Description
id	string
lockup_address	string
routing_fee_milli_sat	uint64	optional	Only populated when zero-conf is accepted and return_immediately is set to false
claim_transaction_id	string	optional	Only populated when zero-conf is accepted and return_immediately is set to false
invoice	string	optional	Invoice to be paid. Only populated when external_pay is set to true

CreateSwapRequest

Field	Type	Label	Description
amount	uint64
pair	Pair		not yet supported repeated string chan_ids = 3;
send_from_internal	bool		the daemon will pay the swap using the onchain wallet specified in the wallet field or any wallet otherwise.
refund_address	string	optional	address where the coins should go if the swap fails. Refunds will go to any of the daemons wallets otherwise.
wallet_id	uint64	optional	wallet to pay swap from. only used if send_from_internal is set to true
invoice	string	optional	invoice to use for the swap. if not set, the daemon will get a new invoice from the lightning node

CreateSwapResponse

Field	Type	Label	Description
id	string
address	string
expected_amount	uint64
bip21	string
tx_id	string		lockup transaction id. Only populated when send_from_internal was specified in the request
timeout_block_height	uint32
timeout_hours	float

CreateTenantRequest

Field	Type	Label	Description
name	string

CreateWalletRequest

Field	Type	Label	Description
params	WalletParams

CreateWalletResponse

Field	Type	Label	Description
mnemonic	string
wallet	Wallet

DepositRequest

Field	Type	Label	Description
inbound_liquidity	uint32		Percentage of inbound liquidity the channel that is opened in case the invoice cannot be paid should have. 25 by default.

DepositResponse

Field	Type	Label	Description
id	string
address	string
timeout_block_height	uint32

Fees

Field	Type	Label	Description
percentage	float
miner	MinerFees

GetInfoRequest

GetInfoResponse

Field	Type	Label	Description
version	string
node	string
network	string
node_pubkey	string
auto_swap_status	string		one of: running, disabled, error
block_heights	BlockHeights		mapping of the currency to the latest block height.
refundable_swaps	string	repeated	swaps that need a manual interaction to refund
tenant	Tenant	optional	the currently authenticated tenant
claimable_swaps	string	repeated	swaps that need a manual interaction to claim
symbol	string		Deprecated.
lnd_pubkey	string		Deprecated.
block_height	uint32		Deprecated.
pending_swaps	string	repeated	Deprecated.
pending_reverse_swaps	string	repeated	Deprecated.

GetPairInfoRequest

Field	Type	Label	Description
type	SwapType
pair	Pair

GetPairsResponse

Field	Type	Label	Description
submarine	PairInfo	repeated
reverse	PairInfo	repeated
chain	PairInfo	repeated

GetServiceInfoRequest

GetServiceInfoResponse

Field	Type	Label	Description
fees	Fees
limits	Limits

GetSubaccountsRequest

Field	Type	Label	Description
wallet_id	uint64

GetSubaccountsResponse

Field	Type	Label	Description
current	uint64	optional
subaccounts	Subaccount	repeated

GetSwapInfoRequest

Field	Type	Label	Description
id	string

GetSwapInfoResponse

Field	Type	Label	Description
swap	SwapInfo
channel_creation	ChannelCreationInfo
reverse_swap	ReverseSwapInfo
chain_swap	ChainSwapInfo

GetTenantRequest

Field	Type	Label	Description
name	string

GetWalletCredentialsRequest

Field	Type	Label	Description
id	uint64
password	string	optional

GetWalletRequest

Field	Type	Label	Description
name	string	optional
id	uint64	optional

GetWalletsRequest

Field	Type	Label	Description
currency	Currency	optional
include_readonly	bool	optional

ImportWalletRequest

Field	Type	Label	Description
credentials	WalletCredentials
params	WalletParams

ImportWalletResponse

LightningChannel

Field	Type	Label	Description
id	ChannelId
capacity	uint64
outbound_sat	uint64
inbound_sat	uint64
peer_id	string

Limits

Field	Type	Label	Description
minimal	uint64
maximal	uint64
maximal_zero_conf_amount	uint64

ListSwapsRequest

Field	Type	Label	Description
from	Currency	optional
to	Currency	optional
is_auto	bool	optional
state	SwapState	optional

ListSwapsResponse

Field	Type	Label	Description
swaps	SwapInfo	repeated
channel_creations	CombinedChannelSwapInfo	repeated
reverse_swaps	ReverseSwapInfo	repeated
chain_swaps	ChainSwapInfo	repeated

ListTenantsRequest

ListTenantsResponse

Field	Type	Label	Description
tenants	Tenant	repeated

MacaroonPermissions

Field	Type	Label	Description
action	MacaroonAction

MinerFees

Field	Type	Label	Description
normal	uint32
reverse	uint32

Pair

Field	Type	Label	Description
from	Currency
to	Currency

PairInfo

Field	Type	Label	Description
pair	Pair
fees	SwapFees
limits	Limits
hash	string

RefundSwapRequest

Field	Type	Label	Description
id	string
address	string
wallet_id	uint64

RemoveWalletRequest

Field	Type	Label	Description
id	uint64

RemoveWalletResponse

ReverseSwapInfo

Field	Type	Label	Description
id	string
state	SwapState
error	string
status	string		Latest status message of the Boltz backend
private_key	string
preimage	string
redeem_script	string
invoice	string
claim_address	string
onchain_amount	int64
timeout_block_height	uint32
lockup_transaction_id	string
claim_transaction_id	string
pair	Pair
chan_ids	ChannelId	repeated
blinding_key	string	optional
created_at	int64
paid_at	int64	optional	the time when the invoice was paid
service_fee	uint64	optional
onchain_fee	uint64	optional
routing_fee_msat	uint64	optional
external_pay	bool
tenant_id	uint64

SetSubaccountRequest

Field	Type	Label	Description
wallet_id	uint64
subaccount	uint64	optional	The subaccount to use. If not set, a new one will be created.

Subaccount

Field	Type	Label	Description
balance	Balance
pointer	uint64
type	string

SwapFees

Field	Type	Label	Description
percentage	double
miner_fees	uint64

SwapInfo

Field	Type	Label	Description
id	string
pair	Pair
state	SwapState
error	string
status	string		Latest status message of the Boltz backend
private_key	string
preimage	string
redeem_script	string
invoice	string
lockup_address	string
expected_amount	uint64
timeout_block_height	uint32
lockup_transaction_id	string
refund_transaction_id	string		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	string	optional
chan_ids	ChannelId	repeated
blinding_key	string	optional
created_at	int64
service_fee	uint64	optional
onchain_fee	uint64	optional
wallet_id	uint64	optional	internal wallet which was used to pay the swap
tenant_id	uint64

SwapStats

Field	Type	Label	Description
total_fees	uint64
total_amount	uint64
avg_fees	uint64
avg_amount	uint64
count	uint64

Tenant

Field	Type	Label	Description
id	uint64
name	string

UnlockRequest

Field	Type	Label	Description
password	string

VerifyWalletPasswordRequest

Field	Type	Label	Description
password	string

VerifyWalletPasswordResponse

Field	Type	Label	Description
correct	bool

Wallet

Field	Type	Label	Description
id	uint64
name	string
currency	Currency
readonly	bool
balance	Balance
tenant_id	uint64

WalletCredentials

Field	Type	Label	Description
mnemonic	string	optional	only one of these is allowed to be present
xpub	string	optional
core_descriptor	string	optional
subaccount	uint64	optional	only used in combination with mnemonic

WalletParams

Field	Type	Label	Description
name	string
currency	Currency
password	string	optional	the password to encrypt the wallet with. If there are existing encrypted wallets, the same password has to be used.

Wallets

Field	Type	Label	Description
wallets	Wallet	repeated

Enums

Currency

Name	Number	Description
BTC	0
LBTC	1

MacaroonAction

Name	Number	Description
READ	0
WRITE	1

SwapState

Name	Number	Description
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

Name	Number	Description
SUBMARINE	0
REVERSE	1
CHAIN	2

autoswaprpc.AutoSwap

Methods

GetRecommendations

Returns a list of swaps which are currently recommended by autoswap. Also works when autoswap is not running.

Request	Response
GetRecommendationsRequest	GetRecommendationsResponse

GetStatus

Returns the current budget of autoswap and some relevant stats.

Request	Response
GetStatusRequest	GetStatusResponse

UpdateLightningConfig

Updates the lightning configuration entirely or partially. Autoswap will reload the configuration after this call.

Request	Response
UpdateLightningConfigRequest	Config

UpdateChainConfig

Updates the chain configuration entirely or partially. Autoswap will reload the configuration after this call.

Request	Response
UpdateChainConfigRequest	Config

GetConfig

Returns the currently used configurationencoded as json. If a key is specfied, only the value of that key will be returned.

Request	Response
GetConfigRequest	Config

ReloadConfig

Reloads the configuration from disk.

Request	Response
.google.protobuf.Empty	Config

Messages

Budget

Field	Type	Label	Description
total	uint64
remaining	int64
start_date	int64
end_date	int64
stats	boltzrpc.SwapStats	optional

ChainConfig

Field	Type	Label	Description
enabled	bool
from_wallet	string
to_wallet	string
to_address	string
max_balance	uint64
max_fee_percent	float
budget	uint64
budget_interval	uint64
tenant	string	optional

ChainRecommendation

Field	Type	Label	Description
amount	uint64
fee_estimate	uint64
dismissed_reasons	string	repeated	any reasons why the recommendation is not being executed

Config

Field	Type	Label	Description
chain	ChainConfig	repeated
lightning	LightningConfig	repeated

GetConfigRequest

GetRecommendationsRequest

GetRecommendationsResponse

Field	Type	Label	Description
lightning	LightningRecommendation	repeated
chain	ChainRecommendation	repeated

GetStatusRequest

GetStatusResponse

Field	Type	Label	Description
lightning	Status	optional
chain	Status	optional

LightningConfig

Field	Type	Label	Description
enabled	bool
channel_poll_interval	uint64
static_address	string
outbound_balance	uint64
inbound_balance	uint64
outbound_balance_percent	float
inbound_balance_percent	float
max_fee_percent	float
accept_zero_conf	bool
failure_backoff	uint64
budget	uint64
budget_interval	uint64
currency	boltzrpc.Currency
swap_type	string
per_channel	bool
wallet	string
max_swap_amount	uint64
tenant	string	optional

LightningRecommendation

Field	Type	Label	Description
amount	uint64
fee_estimate	uint64
dismissed_reasons	string	repeated	any reasons why the recommendation is not being executed
type	string
channel	boltzrpc.LightningChannel

Status

Field	Type	Label	Description
running	bool
error	string	optional
budget	Budget	optional
description	string

UpdateChainConfigRequest

Field	Type	Label	Description
config	ChainConfig
field_mask	google.protobuf.FieldMask	optional
reset	bool	optional

UpdateLightningConfigRequest

Field	Type	Label	Description
config	LightningConfig	optional
field_mask	google.protobuf.FieldMask
reset	bool	optional

Enums

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)