🤖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 or the swap does not have an associated wallet.

Request	Response
RefundSwapRequest	GetSwapInfoResponse

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	WalletCredentials

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
WalletInfo	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

CreateEntity

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

Request	Response
CreateEntityRequest	Entity

ListEntities

Returns all entities.

Request	Response
ListEntitiesRequest	ListEntitiesResponse

GetEntity

Get a specifiy entity.

Request	Response
GetEntityRequest	Entity

BakeMacaroon

Bakes a new macaroon with the specified permissions. The macaroon can also be restricted to a specific entity. In this case, - any swap or wallet created with the returned macaroon will belong to this entity and can not be accessed by other entities. - 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
entity_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	float
onchain_fee	uint64	optional
created_at	int64
entity_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

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

CreateEntityRequest

Field	Type	Label	Description
name	string

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.

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

CreateWalletRequest

Field	Type	Label	Description
info	WalletInfo
password	string	optional	the password to encrypt the wallet with. If there are existing ecnrypted wallets, the same password will have to be used.

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

Entity

Field	Type	Label	Description
id	uint64
name	string

Fees

Field	Type	Label	Description
percentage	float
miner	MinerFees

GetEntityRequest

Field	Type	Label	Description
name	string

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
entity	Entity	optional	the currently authenticated entity
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

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

GetWalletCredentialsRequest

Field	Type	Label	Description
name	string
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
info	WalletInfo
password	string	optional	the password to encrypt the wallet with. If there are existing ecnrypted wallets, the same password will have to be used.

ImportWalletResponse

LightningChannel

Field	Type	Label	Description
id	ChannelId
capacity	uint64
local_sat	uint64
remote_sat	uint64
peer_id	string

Limits

Field	Type	Label	Description
minimal	uint64
maximal	uint64
maximal_zero_conf_amount	uint64

ListEntitiesRequest

ListEntitiesResponse

Field	Type	Label	Description
entities	Entity	repeated

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

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

RemoveWalletRequest

Field	Type	Label	Description
name	string

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
service_fee	uint64	optional
onchain_fee	uint64	optional
routing_fee_msat	uint64	optional
external_pay	bool
entity_id	uint64

SetSubaccountRequest

Field	Type	Label	Description
name	string
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	float
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
entity_id	uint64

SwapStats

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

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
entity_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

WalletInfo

Field	Type	Label	Description
name	string
currency	Currency

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

GetSwapRecommendations

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

Request	Response
GetSwapRecommendationsRequest	GetSwapRecommendationsResponse

GetStatus

Returns the current budget of autoswap and some relevant stats.

Request	Response
GetStatusRequest	GetStatusResponse

ResetConfig

Resets the configuration to default values.

Request	Response
.google.protobuf.Empty	Config

SetConfig

Allows setting multiple json-encoded config values at once. Autoswap will reload the configuration after this call.

Request	Response
Config	Config

SetConfigValue

Allows setting a specific value in the configuration. Autoswap will reload the configuration after this call.

Request	Response
SetConfigValueRequest	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

Config

Field	Type	Label	Description
enabled	bool
channel_poll_interval	uint64
static_address	string
max_balance	uint64
min_balance	uint64
max_balance_percent	float
min_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

GetConfigRequest

Field	Type	Label	Description
key	string	optional

GetStatusRequest

GetStatusResponse

Field	Type	Label	Description
running	bool
strategy	string
error	string
stats	boltzrpc.SwapStats	optional
budget	Budget	optional

GetSwapRecommendationsRequest

Field	Type	Label	Description
no_dismissed	bool	optional	Do not return any dismissed recommendations

GetSwapRecommendationsResponse

Field	Type	Label	Description
swaps	SwapRecommendation	repeated

SetConfigValueRequest

Field	Type	Label	Description
key	string
value	string

SwapRecommendation

Field	Type	Label	Description
type	string
amount	uint64
channel	boltzrpc.LightningChannel
fee_estimate	uint64
dismissed_reasons	string	repeated

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)