🤖gRPC API
Last updated
Last updated
This page was automatically generated.
Paths for the REST proxy of the gRPC interface can be found here.
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 |
|---|---|
Fetches the latest limits and fees from the Boltz backend API it is connected to.
| Request | Response |
|---|---|
Fetches information about a specific pair for a chain swap.
| Request | Response |
|---|---|
Fetches all available pairs for submarine and reverse swaps.
Returns a list of all swaps, reverse swaps, and chain swaps in the database.
Returns stats of all swaps, reverse swaps, and chain swaps in the database.
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.
Claim swaps manually. This is only required when no claim address has been set and the swap does not have an associated wallet.
Gets all available information about a swap from the database.
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.
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.
Creates a new swap from onchain to lightning.
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.
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.
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.
Creates a new liquid wallet and returns the mnemonic.
Imports an existing wallet.
Sets the subaccount of a wallet. Not supported for readonly wallets.
Returns all subaccounts for a given wallet. Not supported for readonly wallets.
Returns all available wallets.
Returns the current balance and subaccount of a wallet.
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.
Returns recent transactions from a wallet.
Returns the credentials of a wallet. The password will be required if the wallet is encrypted.
Removes a wallet.
Send coins from a wallet. Only the confirmed balance can be spent.
Get a new address of the wallet.
Gracefully stops the daemon.
Unlocks the server. This will be required on startup if there are any encrypted wallets.
Check if the password is correct.
Changes the password for wallet encryption.
Creates a new tenant which can be used to bake restricted macaroons.
Returns all tenants.
Get a specifiy tenant.
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.
Channel creations are an optional extension to a submarine swap in the data types of boltz-client.
Returns a list of swaps which are currently recommended by autoswap. Also works when autoswap is not running.
Returns the current budget of autoswap and some relevant stats.
Updates the lightning configuration entirely or partially. Autoswap will reload the configuration after this call.
Updates the chain configuration entirely or partially. Autoswap will reload the configuration after this call.
Returns the currently used configuration.
Reloads the configuration from disk.
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Name | Number | Description |
|---|---|---|
| Name | Number | Description |
|---|---|---|
| Name | Number | Description |
|---|---|---|
| Name | Number | Description |
|---|---|---|
| Name | Number | Description |
|---|---|---|
| Name | Number | Description |
|---|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Request | Response |
|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| Field | Type | Label | Description |
|---|---|---|---|
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
|---|---|---|---|---|---|---|---|---|
GetSwapInfoResponse stream
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
tenant_id
optional
permissions
repeated
macaroon
total
confirmed
unconfirmed
btc
liquid
optional
total
remaining
start_date
end_date
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
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
old
new
swap_id
ID of the swap to which this channel channel belongs
status
inbound_liquidity
private
funding_transaction_id
funding_transaction_vout
cln
cln style: 832347x2473x1
lnd
lnd style: 915175205006540801
swap_ids
repeated
address
wallet_id
transaction_id
swap
channel_creation
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
amount
inbound_liquidity
Percentage of inbound liquidity the channel that is opened should have. 25 by default.
private
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
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
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
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
name
params
mnemonic
wallet
inbound_liquidity
Percentage of inbound liquidity the channel that is opened in case the invoice cannot be paid should have. 25 by default.
id
address
timeout_block_height
percentage
miner
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.
type
pair
submarine
repeated
reverse
repeated
chain
repeated
fees
limits
include
stats
wallet_id
current
optional
subaccounts
repeated
id
swap
channel_creation
reverse_swap
chain_swap
name
id
password
optional
name
optional
id
optional
currency
optional
include_readonly
optional
credentials
params
id
capacity
outbound_sat
inbound_sat
peer_id
minimal
maximal
maximal_zero_conf_amount
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.
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
tenants
repeated
id
exclude_swap_related
optional
limit
optional
offset
optional
transactions
repeated
action
normal
reverse
from
to
pair
fees
limits
hash
id
address
wallet_id
id
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
wallet_id
subaccount
optional
The subaccount to use. If not set, a new one will be created.
balance
pointer
type
descriptors
repeated
percentage
miner_fees
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
total_fees
total_amount
avg_fees
avg_amount
count
success_count
id
name
swap_id
optional
will be populated for LOCKUP, REFUND and CLAIM
type
address
amount
is_our_address
wether the address is controlled by the wallet
password
password
correct
id
name
currency
readonly
balance
tenant_id
mnemonic
optional
only one of these is allowed to be present
xpub
optional
core_descriptor
optional
subaccount
optional
only used in combination with mnemonic
name
currency
password
optional
the password to encrypt the wallet with. If there are existing encrypted wallets, the same password has to be used.
id
address
amount
amount of sats which would be sent
fee
fee_rate
the fee rate used for the estimation in sat/vbyte
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.
tx_id
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
repeated
BTC
0
LBTC
1
ALL
0
MANUAL
1
AUTO
2
READ
0
WRITE
1
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
SUBMARINE
0
REVERSE
1
CHAIN
2
UNKNOWN
0
LOCKUP
1
REFUND
2
CLAIM
3
CONSOLIDATION
4
total
remaining
start_date
end_date
stats
optional
enabled
from_wallet
to_wallet
to_address
max_balance
reserve_balance
max_fee_percent
budget
budget_interval
tenant
optional
swap
optional
Populated when a swap is recommended based on the current balance of the configured from_wallet
wallet_balance
amount
fee_estimate
dismissed_reasons
repeated
Reasons for which the swap is not being executed
chain
repeated
lightning
repeated
lightning
repeated
chain
repeated
lightning
optional
chain
optional
enabled
channel_poll_interval
static_address
outbound_balance
inbound_balance
outbound_balance_percent
inbound_balance_percent
max_fee_percent
accept_zero_conf
failure_backoff
budget
budget_interval
currency
swap_type
per_channel
wallet
max_swap_amount
tenant
optional
swap
optional
Populated when a swap is recommended for the associated channel, otherwise, the current balances are below the configured thresholds
channel
thresholds
the thresholds for a swap to be recommended for the channel
amount
fee_estimate
type
dismissed_reasons
repeated
Reasons for which the swap is not being executed
inbound
optional
outbound
optional
running
error
optional
budget
optional
description
config
field_mask
optional
reset
optional
config
optional
field_mask
reset
optional
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)