Deezy API (1.0.0)

Download OpenAPI specification:Download

Deezy is your home for lightning liquidity.

Swap instantly from lightning to on-chain bitcoin.

Link an on-chain address to a lightning address.

Earn by providing liquidity.

Keep your channels automatically balanced.

Swap (LN to BTC)

Get Info

Get the current info about the swap service for converting LN btc to on-chain BTC.

The cost of a swap is a combination of the liquidity fee and the on-chain fee. If the swap value is amount_sats with chain fee rate on_chain_sats_per_vbyte, then the total fee of the swap is (amount_sats * liquidity_fee_ppm / 1000000) + (on_chain_sats_per_vbyte * on_chain_bytes_estimate)

Responses
200

Information about the swap service.

get/v1/swap/info
Request samples 
Response samples 
application/json
{
  • "liquidity_fee_ppm": 2000,
  • "on_chain_bytes_estimate": 300,
  • "max_swap_amount_sats": 100000000,
  • "min_swap_amount_sats": 100000,
  • "available": true
}
New (LN to BTC) Swap
Initiate a new swap to send lightning btc in exchange for on-chain btc


SecurityapiToken 
Request 
Request Body schema: application/json
amount_sats
integer
the amount in sats you'd like to swap


 
on_chain_address
string
deezy will send on-chain btc to this provided address


 
on_chain_sats_per_vbyte
integer
the fee rate of the on-chain transaction. lower will be less expensive fee but take longer to confirm. higher will be more expensive but faster.


 
Responses 
200
an invoice and fee information. upon receipt of payment to the provided bolt11_invoice, deezy will send amount_sats to on_chain_address at fee rate on_chain_sats_per_vbyte, then settle the invoice. the value fee_sats covers on-chain fees and service costs.


post/v1/swap
Request samples 
application/json
{
  • "amount_sats": 500000,
  • "on_chain_address": "tb1qrcdhlm0mk5lp4r3lx3sjgg2avryp76v2lul3qc",
  • "on_chain_sats_per_vbyte": 2
}
Response samples 
application/json
{
  • "bolt11_invoice": "lntb603u1p3vmxj7pp547868h4ruy4at0xarpftg2akckgy5nlaucsur8uztvuq3y0u7eyqd9dgdhk6mtfw3kk2mn5yp6x7grnwashqgpkxqcrqvpqv96zqumpw3ej7anzyqcjqar0ypskgerjv4ehxgr5vgchzunrv35xcmfsd44n2mrsx3erxmrcxdek5em8xfshvunewqmnva3jd36kcvm3vvsxvmmjypnx2efqxvcrqgrnv968xcqzpgxqzrcsp5x8lvqphg6qn2xjz65yk79hmejnkld6wnf8egcse225zrxf34fnks9qyyssqc3rta3lkug5fxyse50d06wfxvnv30eyfpa9dlwu9aj95ptd9xwqj50zvy6m8c0tx3jlsnzrgavr7jcehga56s0ve303cznm4y76z3ecpuzsdph",
  • "fee_sats": 600
}
Lookup (LN to BTC) Swap
Lookup the on-chain transaction information for an existing swap


SecurityapiToken 
Request 
query Parameters
bolt11_invoice
required
string
the invoice for the swap


 
Responses 
200
Returns the on_chain_txid and tx_hex if they exist, or null if they don't exist yet


get/v1/swap/lookup
Request samples 
Response samples 
application/json
{
  • "on_chain_txid": "string",
  • "tx_hex": "string"
}
Swap (BTC to LN)
New On-Chain Deposit Address
Generate an on-chain address linked to your lnurl or lightning address. Any deposits to this on-chain address will be forwarded via lightning to your lightning address.


Notes:


    

  • The lightning payment deezy makes may be split into several smaller chunks, depending on the max payment size your lnurl allows.
    • 

  • A routing fee will be deducted from the final amount that shows up to your lightning address.
    • 

  • In the event that the lightning payment(s) cannot be completed, you can reach out to support@deezy.io to coordinate a refund, and use the secret_access_key returned in the response body to authenticate yourself (hope to automate this process in future).
    • 



SecurityapiToken 
Request 
Request Body schema: application/json
lnurl_or_lnaddress
required
string
your lnurl or lightning address where you'd like lightning funds to be sent


 
secret_access_key
string
an optional secret to authenticate yourself for viewing status of deposits or coordinating refunds. this must be a secret generated by deezy, so leave this blank if you don't already have one. when you leave this blank, deezy will generate a fresh one and return it in the response, which you can then use for any new deposit addresses in the future if you want to manage them with the same key. a single auth key can be linked to as many or as few new deposit addresses across many different lnurls.


 
webhook_url
string
url to receive updates when new deposits come in to this address. body of the webhook will have the fields lnurl_or_lnaddress, deposit_address, utxo_key, and status (which will be AWAITING_CONFIRMATION, FUNDING_CONFIRMED, or PAYOUT_COMPLETE). note that a bad actor could call your webhook endpoint with fake information, so webhooks should never be trusted. so when getting a webhook you should then call the /v1/source/lookup endpoint to get more information


 
Responses 
200
an on-chain address controlled by deezy


post/v1/source
Request samples 
application/json
{
  • "lnurl_or_lnaddress": "LNURL1DP68GURN8GHJ7MRWW3UXYMM59E3K7MF0D3H82UNV9ACXZ7FLW4EK2UNFVS7NXV34X5MRV4P0TTS",
  • "secret_access_key": "b3c6056d2845867fa7c8edcd2af94876e83c9c86ea15532f7665ecbf26e0f4ec",
  • "webhook_url": "https://your.website.com/deezyhook"
}
Response samples 
application/json
{
  • "address": "bc1qkceyc5yv7gf2n60lnqftjl070fpc08r7jhhtt4",
  • "secret_access_key": "b3c6056d2845867fa7c8edcd2af94876e83c9c86ea15532f7665ecbf26e0f4ec",
  • "commitment": "for any satoshis sent to bc1qkceyc5yv7gf2n60lnqftjl070fpc08r7jhhtt4 and confirmed on chain, deezy will send the equivalent amount over lightning minus routing fees to danny@deezy.io. in the event of an issue, the user can authenticate themself to coordinate a resolution using the secret access key b3c6056d2845867fa7c8edcd2af94876e83c9c86ea15532f7665ecbf26e0f4ec",
  • "signature": "d69j6aj1ssz5egmsr7hd66rpa1crf1bgnym57r9dc8phpwhz89yahhb6zinopnqeyzthjxxzkmktm8ijsibud6cyfisb38znjgk9jwrh",
  • "webhook_url": "https://your.website.com/deezyhook"
}
Lookup (BTC to LN) Swaps
Lookup (BTC to LN) swaps


SecurityapiToken 
Request 
query Parameters
secret_access_key
required
string
the secret access key that you provided when creating the on-chain deposit address(es)


 
Responses 
200
List of all (BTC to LN) swaps connected


get/v1/source/lookup
Request samples 
Response samples 
application/json
{
  • "swaps": [
    ],
  • "total_sent_sats": 0,
  • "total_received_sats": 0,
  • "total_pending_payout_sats": 0,
  • "total_deezy_fees_sats": 0
}
Request Channel
Request Channel
Request a channel from the Deezy node


Request 
Request Body schema: application/json
node_connection_info
required
string
pubkey@host:port of your node


 
remote_balance
required
integer
the amount of liquidity desired on Deezy's side of the channel, in satoshis


 
on_chain_fee_rate
number
the on-chain fee rate for the channel opening transaction in satoshis/vbyte. if not set, will default to next-block fee rate.


 
Responses 
200
Information on the requested channel and how to pay for it


post/v1/lsp/channel
Request samples 
application/json
{
  • "node_connection_info": "021c97a90a411ff2b10dc2a8e32de2f29d2fa49d41bfbb52bd416e460db0747d0d@50.112.125.89:9735",
  • "remote_balance": 10000000,
  • "on_chain_fee_rate": 2
}
Response samples 
application/json
{
  • "order_id": "f311be364d0205f74a58727d098d32a8",
  • "order_total": 11110,
  • "lsp_connection_info": "024bfaf0cabe7f874fd33ebf7c6f4e5385971fc504ef3f492432e9e3ec77e1b5cf@52.1.72.207:9735",
  • "ln_invoice": "lnbc1..."
}
Get Channel Request Info
Get information about a channel request


Request 
query Parameters
id
required
string
the order_id of the requested channel


 
 Example:  id=f311be364d0205f74a58727d098d32a8
Responses 
200
Information about a requested channel


get/v1/lsp/channel
Request samples 
Response samples 
application/json
{
  • "order_id": "string",
  • "remote_balance": 0,
  • "order_total": 0,
  • "ln_invoice": "string",
  • "amount_paid": 0,
  • "channel_open_tx": "string",
  • "state": "string"
}
Earn
Get Earn Info
Get current earning rates for Deezy's earn features


Responses 
200
Earning rates for Deezy's earn features


get/v1/earn/info
Request samples 
Response samples 
application/json
{
  • "close_channel_earn_ppm": 1000
}
Request Earn by Closing Channel
Earn sats immediately by letting Deezy close one of your channels. Deezy will pay you for the amount of liquidity on Deezy's side at the time of channel closure. The channel must have been originally initiated by you. See close_channel_earn_ppm on the 'Get Earn Info' api endpoint for current payout rate. After calling this endpoint with a proper signature, Deezy will pay you and then Deezy will close the channel.


Request 
Request Body schema: application/json
channel_point
required
string
the channel point (utxo-key) of the channel you'd like to close


 
signature
required
string
a signature from your node key of the message close <channel-point> where <channel-point> is the channel point of the channel you'd like to close. an example command to generate this signature using lncli is: 


lncli signmessage "close 6fce9ee4218ba7dd6940dd6bbac710c9c2884923854152e48a7edd9c24cd3043:0"


 
Responses 
200
success response


post/v1/earn/closechannel
Request samples 
application/json
{
  • "channel_point": "6fce9ee4218ba7dd6940dd6bbac710c9c2884923854152e48a7edd9c24cd3043:0",
  • "signature": "d967mbafbuqprz6xkbpu6xxw5qnbpmuysyng9adkgcdbfnd3ntd4ggsm4454x5mk1hitjf3yf1wp54stiroiyiay8ncgoqbsspt3n73w"
}
Response samples 
application/json
{
  • "channel_point": "6fce9ee4218ba7dd6940dd6bbac710c9c2884923854152e48a7edd9c24cd3043:0",
  • "payout_ppm": 1000,
  • "payout_payment_hash": "5dee9327cb5f6821a76531a67862f3743f550931bc160453aa7c8662b2fafba3",
  • "status": "PENDING"
}
Autobalance
Set Autobalance Config
Configure Deezy's autobalancing service to keep your channel with Deezy balanced. Set your preferences with this api endpoint. Each new api call overwrites any old configuration for your node. Once you set your configuration here, you can fund the autobalancer by getting an invoice from the Fund Channel Autobalance endpoint. Works best if you have a single channel with Deezy. If you have multiple channels with Deezy, it will just treat them like one big channel.


Request 
Request Body schema: application/json
node_pubkey
required
string
your node pubkey


 
max_local_balance_sats
number
if the balance on your side of the channel exceeds this, Deezy will attempt to rebalance it back down using max_local_out_ppm


 
max_local_out_ppm
number
Deezy will use this ppm as the max fee rate when trying to rebalance your local balance back below max_local_balance_sats.


 
max_remote_balance_sats
number
if the balance on Deezy's side of the channel exceeds this, Deezy will attempt to rebalance it back down using max_local_in_ppm


 
max_local_in_ppm
number
Deezy will use this ppm as the max fee rate when trying to rebalance your remote balance back below max_local_balance_sats.


 
signature
string
A signature to authenticate your request. The signature is generated like so (commas separating each param): lncli signmessage "autobalance <your_node_pubkey>,<max_local_balance_sats>,<max_local_out_ppm>,<max_remote_balance_sats>,<max_local_in_ppm>". Not all arguments are required, so if some are undefined just leave them empty. For example if you are setting max_local_balance_sats to 1000000 and max_local_out_ppm to 500, but leaving max_remote_balance_sats and max_local_in_ppm blank, your signature will look something like this: lncli signmessage "autobalance 021c97a90a411ff2b10dc2a8e32de2f29d2fa49d41bfbb52bd416e460db0747d0d,1000000,500,,". Alternatively if you are setting max_remote_balance_sats to 3000000 and max_local_in_ppm to 200, but leaving the other options blank, your signing command will look like this: lncli signmessage "autobalance 021c97a90a411ff2b10dc2a8e32de2f29d2fa49d41bfbb52bd416e460db0747d0d,,,3000000,200"


 
Responses 
200
success response


post/v1/autobalance/config
Request samples 
application/json
{
  • "node_pubkey": "021c97a90a411ff2b10dc2a8e32de2f29d2fa49d41bfbb52bd416e460db0747d0d",
  • "max_local_balance_sats": 3000000,
  • "max_local_out_ppm": 500,
  • "max_remote_balance_sats": 7000000,
  • "max_local_in_ppm": 600,
  • "signature": "string"
}
Response samples 
application/json
{
  • "message": "autobalance successfully configured. use the /v1/autobalance/fund endpoint to set your budget"
}
Fund Autobalance
Fund your autobalance budget. Deezy will use the budget to keep your Deezy channel balanced according to the settings you've set in the Set Channel Autobalance Config endpoint. Request a refund at any time to get back the unused portion of your budget


Request 
Request Body schema: application/json
node_pubkey
required
string
your node pubkey


 
signature
string
A signature to authenticate your request. The signature is generated like so lncli signmessage "autobalance fund <your_node_pubkey>". For example: lncli signmessage "autobalance fund 021c97a90a411ff2b10dc2a8e32de2f29d2fa49d41bfbb52bd416e460db0747d0d"


 
Responses 
200
success response


post/v1/autobalance/fund
Request samples 
application/json
{
  • "node_pubkey": "021c97a90a411ff2b10dc2a8e32de2f29d2fa49d41bfbb52bd416e460db0747d0d",
  • "signature": "string"
}
Response samples 
application/json
{
  • "bolt11_invoice": "lnbc1...."
}
Get Autobalance Info
Get information about your autobalance configuration, budget, and history


Request 
query Parameters
node_pubkey
required
string
your node pubkey


 
signature
required
string
signature using lncli signmessage of the message autobalance info <your_node_pubkey>, example: lncli signmessage "autobalance info 021c97a90a411ff2b10dc2a8e32de2f29d2fa49d41bfbb52bd416e460db0747d0d"


 
Responses 
200
success response


get/v1/autobalance/info
Request samples 
Response samples 
application/json
{
  • "budget_remaining_msats": 20000000,
  • "total_budget_funded_msats": 30000000,
  • "total_budget_spent_msats": 10000000,
  • "total_budget_refunded_msats": 10000000,
  • "total_deezy_fees_msats": 0,
  • "budget_funding_payments": [
    ],
  • "budget_refund_payments": [
    ],
  • "autobalances": [
    ],
  • "current_config": {
    }
}
Refund Autobalance Budget (DRAFT - not implemented yet)
Request a refund of the unused budget for a given channel autobalance configuration.


Request 
Request Body schema: application/json
node_pubkey
required
string
your node pubkey


 
bolt11_invoice
required
string
A bolt11 invoice from your node. The amount must be blank. It must be from your node. Your entire remaining budget will be refunded once any pending rebalance payments complete.


 
Responses 
200
success response


post/v1/autobalance/refund
Request samples 
application/json
{
  • "node_pubkey": "021c97a90a411ff2b10dc2a8e32de2f29d2fa49d41bfbb52bd416e460db0747d0d",
  • "bolt11_invoice": "lnbc1...."
}
Response samples 
application/json
{ }
Inscriptions
Get Info About an Inscriptions Collection
Get information about an inscriptions collection


Request 
query Parameters
collection_id
required
string
The collection_id of the collection. To get a collection_id you must register your collection with support@deezy.io


 
Responses 
200
success response


get/v1/inscriptions/collections/info
Request samples 
Response samples 
application/json
{
  • "num_available": 970,
  • "max_supply": 10000,
  • "price_sats": 100000,
  • "base_price_sats": 80000,
  • "fee_rate_multiplier": 80000,
  • "max_per_mint": 10,
  • "phase": 2
}
Mint Inscriptions from a Collection
Mint one or more inscriptions from a collection


Request 
Request Body schema: application/json
collection_id
required
string
the collection_id of the collection you want to mint from


 
num_to_mint
required
number
The number of inscriptions to mint in this transaction


 
receive_address
required
string
The on-chain bitcoin address to receive the inscriptions. Warning: this should be dedicated ordinals wallet that does not intermingle with normal funds. If you receive to a wallet that is used for other purposes, you may lose your items.


 
fee_rate
required
number
The desired on-chain fee rate of the minting transaction in sats/vbyte


 
payment_type
string
How the user will pay for the item. Either LIGHTNING or STRIPE. If blank, both a lightning invoice and payment_intent will be returned


 
receive_email
string
The email address where the user will receive a key for their items. Must set exactly one of receive_address or receive_email


 
Responses 
200
success response


post/v1/inscriptions/collections/mint
Request samples 
application/json
{
  • "collection_id": "b3c6056d2845867fa7c8edcd2af94876",
  • "num_to_mint": 3,
  • "receive_address": "bc1q...",
  • "fee_rate": 2.5,
  • "payment_type": "LIGHTNING",
  • "receive_email": "spongebob@nick.com"
}
Response samples 
application/json
{
  • "bolt11_invoice": "lnbc1....",
  • "mint_attempt_id": "fa7c8edcd2af94876b3c6056d2845867",
  • "payment_intent": "....",
  • "payment_address": "bc1q...",
  • "amount_sats": 100000
}
Get Info About a Mint Attempt
Get information about an attempted mint transaction


Request 
query Parameters
mint_id
required
string
The mint_id of the mint transaction.


 
Responses 
200
success response


get/v1/inscriptions/mint
Request samples 
Response samples 
application/json
{
  • "mint_id": "fa7c8edcd2af94876b3c6056d2845867",
  • "collection_id": "b3c6056d2845867fa7c8edcd2af94876",
  • "num_to_mint": 3,
  • "receive_address": "bc1q...",
  • "bolt11_invoice": "lnbc1....",
  • "payment_hash": "fa7c8edcd2af94876b3c6056d2845867",
  • "payment_address": "bc1q...",
  • "amount_sats": 100000,
  • "status": "",
  • "mint_outpoints": [
    ]
}
Mint a Custom Inscription
Mint a custom inscription


Request 
Request Body schema: application/json
file_data_base64
required
string
the file data of the inscription you'd like to mint


 
file_extension
required
string
the extension (file type) of the provided file


 
on_chain_fee_rate
number
the desired on-chain fee rate of the mint transaction, in satoshis/vbyte (default: 1)


 
receive_address
required
string
The on-chain bitcoin address to receive the inscription. Warning: this should be dedicated ordinals wallet that does not intermingle with normal funds. If you receive to a wallet that is used for other purposes, you may lose your items.


 
Responses 
200
success response


post/v1/inscriptions/mint
Request samples 
application/json
{
  • "file_data_base64": "s8YFbShFhn+nyO3NKvlIdg==",
  • "file_extension": "png",
  • "on_chain_fee_rate": 1,
  • "receive_address": "bc1q..."
}
Response samples 
application/json
{
  • "bolt11_invoice": "lnbc1....",
  • "mint_attempt_id": "fa7c8edcd2af94876b3c6056d2845867"
}
Collection Allowlist Info
Check whether an address is on the allowlist for a collection


Request 
query Parameters
collection_id
required
string
The collection id


 
address
required
string
The bitcoin address


 
Responses 
200
success response


get/v1/inscriptions/collections/allowlist
Request samples 
Response samples 
application/json
{
  • "address": "bc1...",
  • "num_allowed": 2,
  • "num_used": 1
}
Update Collection Allowlist for Single Address
Update the number of allowed mints for an address in a collection. This endpoint allows you to update details one address at a time.


Request 
Request Body schema: application/json
collection_id
required
string
The collection id


 
address
required
string
The bitcoin address


 
num_allowed
required
number
The number of mints this address is allowed in this collection


 
secret_key
required
string
A secret key that is used to authenticate this request. Get one of these for your collection by contacting support@deezy.io


 
Responses 
200
success response


put/v1/inscriptions/collections/allowlist
Request samples 
application/json
{
  • "collection_id": "fa7c8edcd2af94876b3c6056d2845867",
  • "address": "bc1...",
  • "num_allowed": 2,
  • "secret_key": "af94876b3c645867fa7c8edcd2056d28"
}
Response samples 
application/json
{ }
Boost
Boost a utxo (ordinal) that is low on sats
If sent too much, an ordinal can run out of juice to pay for itself. Use this API endpoint to boost the ordinal with more sats. Create a half-signed PSBT and post it to this endpoint, pay the invoice, and Deezy will add and input to boost the value of the ordinal.


Request 
Request Body schema: application/json
psbt
required
string
The half-signed psbt as a hex string. The psbt should have a single ordinal as input and one 10,000 sat output. The input should be signed with SIGHASH_SINGLE | SIGHASH_ANYONECANPAY. See example at https://github.com/dannydeezy/nosft


 
fee_rate
required
number
The desired fee rate of the boost transaction in sats/vbyte


 
Responses 
200
success response


post/v1/boost
Request samples 
application/json
{
  • "psbt": "70736274ff010052020000000135a0a3c9deb5935ad4a6e46a288f175710e66b67834456693db9889c77819b0e0000000000ffffffff011027000000000000160014e3718cb2b07cdfcc5829cac03041985ff405bda800000000000100de02000000000101b667693b2c390a1a471470de5b84149ae813b27aa3d82110ce1f3784505f35b60100000000feffffff022c01000000000000160014e3718cb2b07cdfcc5829cac03041985ff405bda8b2430f0000000000160014ad198770eed2273c50ec6d450fc8476496bd7aa8024730440220679eb1e45d36122c5c6c55bad8471efdb31182f72a76154d30603e938b503218022041c529d0c533f8ef8e096b46a216a7a9907d5447b2fb9f7aafa7d36f5c8e4123012103bccfc8d7762460d30176e62e4282c8f1b0f11eb5fdbd59d6ef9fae3abee93271b4f9240001011d2c0100000000000014e3718cb2b07cdfcc5829cac03041985ff405bda801086c02483045022100cf0e166edaab012a94b0040ef98800a81b270e7ad33f983bed4abac3b855c42c02204b03099c18479744faed3e45b2b65436f2db31fbd2d8822024a4adeae9bb192383210334903b6e2a8134171da9a363184a928894a73ede4ff0725b9739af197b6a4a100000",
  • "fee_rate": 3
}
Response samples 
application/json
{
  • "bolt11_invoice": "lnbc1...."
}