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.

Sat Hunting

Scan a UTXO or Address for Special Sats

Initiate a scanning operation to look for special sats in a UTXO or address. Either utxo_to_scan or address_to_scan must be provided.

SecurityapiToken
Request
Request Body schema: application/json
required
One of:
utxo_to_scan
required
string

The UTXO to scan for special satoshis.

extract
boolean

Whether to return a PSBT that extracts the special sats to addresses of your choice

special_sat_addresses
Array of strings

List of addresses (taproot preferred) where you'd like the special sats to be sent to. Must provide at least one address if "extract" is true. If there are more special sat outputs than addresses provided, we will re-use the addresses provided as needed.

regular_funds_addresses
Array of strings

List of addresses (taproot preferred) where you'd like the regular (non-special) sats sent to. Must provide at least one address if "extract" is true. If there are more regular sat outputs than addresses provided, we will re-use the addresses provided as needed.

extraction_fee_rate
number

Optional fee rate in sats/vbyte of the extraction transaction. If not provided, we will use the current next block minimum fee rate.

excluded_tags
Array of strings

Optional list of tag combinations to exclude from the scan. The default value for the excluded tags, if not provided, is [['omega'], ['alpha'], ['block_78'], ['vintage_nakamoto'], ['pizza']]. To scan the full set of tags, pass an empty array.

included_tags
Array of strings

Optional list of tag combinations to include from the scan. If included_tags is set, it will override excluded_tags settings.

object

Optional mapping of tag names to their minimum size values for filtering. The key is the tag name and the value is the minimum sat size required for that tag to be extracted.

object

You can use the optional mapping of tag names to their maximum age values for filtering. This allows you to specify the maximum year for a tag to be considered, and the tag will only be included if it is from that year or earlier. The key should be the tag name, and the value should be the maximum year (inclusive). This is a sub-filter applied before excluded_tags or included_tags.

object

Optional mapping of tag names to their maximum number of satoshis to be extracted. The key is the tag name and the value is the maximum number of satoshis allowed for that tag to be extracted.

object

An object mapping rarity tags to Bitcoin addresses. This is used to direct special satoshis identified by their rarity tags to specific addresses. The script will use the first matching tag to determine where to send the sat. The order of the tag:address pairs in your configuration matters. For example, if your configuration is { 'uncommon': 'address123', 'omega': 'address345' } and the script finds an uncommon omega sat, it will be sent to 'address123'. However, if your configuration is { 'omega': 'address345', 'uncommon': 'address123' }, the sat would be sent to 'address345'.

Combination of multiple tags is also allowed, ex: { 'omega/block_78': 'address345'}. This will direct bundle to 'address345' if it has both omega and block_78 tags.

split_trigger
string

Optional parameter saying when to split the outputs to regular funds addresses into smaller chunks. Options are NEVER (default), NO_SATS (split only when no special sats are found) or ALWAYS (always split). This can be useful to shake up the coin selection of an exchange if they happen to return the same sats to you over and over again. Splitting up the outputs can cause the exchange to give you fresh sats on your next withdrawal.

split_target_size_sats
integer

The target output size of the regular funds outputs when splitting is enabled.

withdraw_address
string

Optional parameter saying when to attempt to create an output of withdraw_size_sats amount to the specified address within the extraction PSBT.

withdraw_size_sats
integer

The target output size of the withdrawal output when withdrawal_address is provided.

split_special_ranges
boolean

Whether to split large chunk of sats, if it contains another special sats (subset). Large chunk will be split into: [A, B, CHANGE] or [A, B, A] if sets are valid accordingly to minimum sizes configurations

Ex: you have 5M of block_9 with 600 sats of 450x inside, MIN_TAG_SIZES is 1M for block_9. Enabling this flag will result into outputs of 4.5M block_9, 600 block_9 450x, rest will go to change since remaining is less then 1M.

Responses
200

ID of the scan operation

500

Internal Server Error

post/v1/sat-hunting/scan
Request samples
application/json
{
  • "address_to_scan": "bc1qy3c3vn2pfrmk8t5qt2apqqxx48l80senpfmqqh",
  • "extract": true,
  • "special_sat_addresses": [
    ],
  • "regular_funds_addresses": [
    ],
  • "extraction_fee_rate": 10,
  • "excluded_tags": [
    ],
  • "included_tags": [
    ],
  • "min_tag_sizes": {
    },
  • "max_tag_ages": {
    },
  • "tag_limits": {
    },
  • "tag_by_address": {
    },
  • "split_trigger": "NEVER",
  • "split_target_size_sats": 100000000,
  • "withdraw_address": "bc1q2utnxf5d4y2vqmly5w675dqxtgd0fqhnezmq52",
  • "withdraw_size_sats": 100000000,
  • "split_special_ranges": false
}
Response samples
application/json
{
  • "id": "20a27d48e7ae0db029a01b1fd06fd6d8"
}

Get Result of UTXO or Address Scan

It can be used to check the status of a scanning operation, and to retrieve the results of a completed scan.

SecurityapiToken
Request
path Parameters
id
required
string

The ID of the scanning operation, as returned from the earlier POST request

Responses
200

Rare Sat Info for the Provided UTXO or address

500

Internal Server Error

get/v1/sat-hunting/scan/{id}
Request samples 
Response samples 
application/json
{
  • "status": "COMPLETED",
  • "utxo": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b:0",
  • "address": "bc1qy3c3vn2pfrmk8t5qt2apqqxx48l80senpfmqqh",
  • "satributes": [
    ],
  • "extraction_psbt": "cHNidP8BAHECAAAAAeJQY2VLRtutKgQYFUajEKpjFfl0Uyrm6x23OumDpe/4AQAAAAD/////AkxREgEAAAAAFgAUv6pTgbKHN60CZ+RQn5yOuH6c2WiA8PoCAAAAABYAFJDbOFU0E6zFF/M+g/AKDyqI2iUaAAAAAAABAOsCAAAAAAEBbxqXgEf9DlzcqqNM610s5pL1X258ra6+KJ22etb7HAcBAAAAAAAAAAACACT0AAAAAAAiACC7U1W0iJGhQ6o7CexDh5k36V6v3256xpA9/xmB2BybTFZdDQQAAAAAFgAUKp2ThzhswyM2QHlyvmMB6tQB7V0CSDBFAiEA4Md8RIZYqFdUPsgDyomlzMJL9bJ6Ho23JGTihXtEelgCIAeNXRLyt88SOuuWFVn3IodCE4U5D6DojIHesRmikF28ASEDHYFzMEAxfmfq98eSSnZtUwb1w7mAtHG65y8qiRFNnIkAAAAAAQEfVl0NBAAAAAAWABQqnZOHOGzDIzZAeXK+YwHq1AHtXQEDBAEAAAAAAAA=",
  • "excluded_tags": [
    ],
  • "included_tags": [
    ],
  • "min_tag_sizes": {
    },
  • "tag_limits": {
    },
  • "tag_by_address": {
    },
  • "split_trigger": "NEVER",
  • "split_target_size_sats": 100000000,
  • "withdraw_address": "bc1q2utnxf5d4y2vqmly5w675dqxtgd0fqhnezmq52",
  • "withdraw_size_sats": 100000000,
  • "withdraw_success": true,
  • "split_special_ranges": true
}
Get status of UTXO Scans
Get the status of scanning operations.


SecurityapiToken 
Request 
query Parameters
limit
integer
The number of requests to return. Defaults to 100.


 
offset
integer
The offset of requests to return. Defaults to 0.


 
Responses 
200
Scan requests for the Provided API User


500
Internal Server Error


get/v1/sat-hunting/scans
Request samples 
Response samples 
application/json
[
  • {
    }
]
Get Rarity Tags
Get list of recognized rarity tags; these values can be used for the excluded_tags and included_tags parameters in the scan request.


SecurityapiToken 
Responses 
200
Currently recognized rarity tags for sat scanning


500
Internal Server Error


get/v1/sat-hunting/tags
Request samples 
Response samples 
application/json
{
  • "rarity_tags": "mythic"
}
Get User Limits
This endpoint retrieves the user limits for sat hunting. The user's plan allows for a certain amount of BTC every certain number of days, and allows purchasing additional volume at a rate of a certain number of satoshis per 1 BTC of scan volume. Contact help@deezy.io for questions or to change your plan.


Request 
header Parameters
x-api-token
required
string
API token for the user


 
Responses 
200
Success response. Returns the user's limits for sat hunting, including the amount limit, unit of the amount, number of days for the limit, subscription cost, one-time cost, and user volume.


400
Bad request response


get/v1/sat-hunting/user/limits
Request samples 
Response samples 
application/json
{
  • "payment_address": "1bc1q...",
  • "amount": 97666993630,
  • "unit": "sats",
  • "days": 30,
  • "subscription_cost": 100000000,
  • "one_time_cost": 200000,
  • "user_volume": 97666993631,
  • "remaining_volume": 97666993631
}
Get Earnings Summary (DRAFT - not implemented yet)
Retrieves a summary of earnings based on specified criteria. It allows grouping by specific attributes such as year, month, etc., and filtering based on the number of days ago.


SecurityapiToken 
Request 
query Parameters
group_by
string
Group the results by a specified attribute. Valid values include: 'year', 'month', 'epoch', 'period', or 'block'.


 
days_ago
integer
 Default:  30
Filter the results to include data from the specified number of days ago. Defaults to 30 days.


 
Responses 
200
A summary of earnings with optional grouping and time-based filtering.


500
Internal Server Error


get/v1/sat-hunting/earnings
Request samples 
Response samples 
application/json
{
  • "summary": [
    ],
  • "group_by": "string",
  • "days_ago": 0
}
Get Circulation Data
Get the circulation data of sats


SecurityapiToken 
Request 
query Parameters
rarity
required
string
The rarity tag(s) to filter by. Examples: ?rarity=uncommon or can do multiple tags like: ?rarity=uncommon,pizza. Valid rarities are: 2009, uncommon, rare, epic, black_uncommon, black_rare, black_epic, palindrome, jan2009, vintage, nakamoto, pizza, jpeg, hitman, silkroad, alpha, omega, 1_digit, 2_digits, 3_digits, perfect_palinception, uniform_palinception, rodarmor, 450x, block_9, block_78, block_286, block_666, fibonacci


 
block
integer
Filter by a specific block. Example: ?rarity=perfect_palinception&block=666


 
block_start
integer
Only search for sats mined at this block height or later. Example: ?rarity=perfect_palinception&block_start=10000. Can be used in combination with block_end.


 
block_end
integer
Only search for sats mined at this block height or earlier. Example: ?rarity=perfect_palinception&block_end=10000. Can be used in combination with block_start.


 
time_start
string <date-time> 
Only search for sats mined after this datetime or later. Example: ?rarity=perfect_palinception&time_start=2009-01-01T14:15:22Z or ?rarity=perfect_palinception&time_start=2009-01-01. Can be used in combination with time_end.


 
time_end
string <date-time> 
Only search for sats mined before this datetime or earlier. Example: ?rarity=perfect_palinception&time_end=2010-01-01T14:15:22Z or ?rarity=perfect_palinception&time_end=2010-01-01. Can be used in combination with time_start.


 
Responses 
200
Circulation data for the specified rarity tag(s)


500
Internal Server Error


get/v1/sat-hunting/circulation
Request samples 
Response samples 
application/json
{
  • "data": {
    }
}
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)


SecurityapiToken 
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,
  • "partner_fee_ppm": 1000,
  • "deezy_fee_ppm": 1000
}
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
required
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.


 
deezy_user_id
string
The external_id of the user initiating the swap. The user must have passed kyc verification.


 
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,
  • "deezy_user_id": "cfdaa3b0-9dbc-4a9d-9e4c-0f1f5a9a8a5b"
}
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
required
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


 
deezy_user_id
string
The external_id of the user initiating the swap. The user must have passed kyc verification.


 
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",
  • "deezy_user_id": "cfdaa3b0-9dbc-4a9d-9e4c-0f1f5a9a8a5b"
}
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,
  • "total_partner_fees_sats": 0
}
KYC Users
Create a user
Create a user. A user represents an individual person and must fill out all required KYC documentation before using the service.


SecurityapiToken 
Request 
Request Body schema: application/json
required
external_id
string
A unique identifier for the user. If you do not provide one, we will generate one for you.


 
Responses 
200
User created successfully


post/v1/user
Request samples 
application/json
{
  • "external_id": "cfdaa3b0-9dbc-4a9d-9e4c-0f1f5a9a8a5b"
}
Response samples 
application/json
{
  • "external_id": "cfdaa3b0-9dbc-4a9d-9e4c-0f1f5a9a8a5b"
}
Get info about one of your users
Get info about one of your users


SecurityapiToken 
Request 
path Parameters
external_id
required
string
The ID of the user


 
Responses 
200
KYC status info about a user


500
Internal Server Error


get/v1/user/{external_id}
Request samples 
Response samples 
application/json
{}
Request Channel
Request Channel
Request a channel from the Deezy node


Request 
Request Body schema: application/json
required
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
required
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"
}
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,
  • "num_minted": 21,
  • "max_supply": 10000,
  • "price_sats": 100000,
  • "base_price_sats": 80000,
  • "fee_rate_multiplier": 80000,
  • "max_per_mint": 10,
  • "allowlist_enabled": false
}
Mint Inscriptions from a Collection
Mint one or more inscriptions from a collection


Request 
Request Body schema: application/json
required
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
required
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.


 
cursed
boolean
curse ye inscription - advanced use only


 
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...",
  • "cursed": false
}
Response samples 
application/json
{
  • "bolt11_invoice": "lnbc1....",
  • "mint_attempt_id": "fa7c8edcd2af94876b3c6056d2845867",
  • "payment_intent": "....",
  • "payment_address": "bc1q...",
  • "amount_sats": 100000
}
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
required
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
{ }
Buy an Ordinal
Buy a PSBT-listed ordinal with a lightning payment


Request 
Request Body schema: application/json
required
psbt
required
string
PSBT of the listed ordinal, encoded as Hex or Base64. This should be a one-input, one-output PSBT signed with Sighash Single | Sighash Anyonecanpay in accordance with the Offers spec: https://github.com/casey/ord/issues/802


 
receive_address
required
string
The on-chain bitcoin address to receive the ordinal. 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.


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


 
refund_lightning_address
required
string
A lightning address or LNURL (i.e. deezy@getalby.com or lnurl1dp68gurn8ghj7mr...). This is where the user will be refunded if for some reason the trade fails.


 
processor
string
For commercial agreement use only.


 
Responses 
200
success response


post/v1/inscriptions/buy
Request samples 
application/json
{
  • "psbt": "70736274ff01009a0200000001...",
  • "receive_address": "bc1q...",
  • "on_chain_fee_rate": 2.5,
  • "refund_lightning_address": "deezy@getalby.com",
  • "processor": ""
}
Response samples 
application/json
{
  • "purchase_id": "fa7c8edcd2af94876b3c6056d2845867",
  • "bolt11_invoice": "lnbc1...."
}
PSBT
Populate a PSBT to buy an ordinal
Populate a PSBT with dummy inputs and a dummy output, which is useful for buying ordinals on decentralized marketplaces


Request 
Request Body schema: application/json
required
psbt
required
string
PSBT of the listed ordinal, encoded as Hex or Base64. This should be a one-input, one-output PSBT in accordance with the Offers spec: https://github.com/casey/ord/issues/802. The input can either be unsigned or signed with SIGHASH_SINGLE | SIGHASH_ANYONECANPAY.


 
ordinal_receive_address
required
string
The on-chain bitcoin address to receive the ordinal. 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/psbt/populate
Request samples 
application/json
{
  • "psbt": "70736274ff01009a0200000001...",
  • "ordinal_receive_address": "bc1q..."
}
Response samples 
application/json
{
  • "id": "fa7c8edcd2af94876b3c6056d2845867",
  • "psbt": "lnbc1....",
  • "expires_at": "2021-01-01T00:00:00Z"
}
Sign a PSBT to buy an ordinal
Signs the dummy inputs for a PSBT that was populated with the v1/psbt/populate endpoint.


Request 
Request Body schema: application/json
required
id
required
string
The id of the PSBT to sign, as returned by the /v1/psbt/populate endpoint.


 
psbt
required
string
The PSBT to sign. This should be fully funded with as many signatures as possible.


 
Responses 
200
success response


post/v1/psbt/finalize
Request samples 
application/json
{
  • "id": "fa7c8edcd2af94876b3c6056d2845867",
  • "psbt": "70736274ff01009a0200000001..."
}
Response samples 
application/json
{
  • "txid": "fa7c8edcd2af94876b3c6056d2845867",
  • "tx_hex": "lnbc1....",
  • "funded_signed_psbt": "707123123..."
}
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.


Request 
Request Body schema: application/json
required
psbt
required
string
PSBT Hex or Base64 of with one input and one output, unsigned. The output should be of 10,000 sats


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


 
Responses 
200
success response


post/v1/boost-tx
Request samples 
application/json
{
  • "psbt": "70736274ff0100520200000001dcb84258fd10be481d1fcce713d98111c1098d8a2a6a8549765442a85eb3b6190000000000ffffffff011027000000000000160014e3718cb2b07cdfcc5829cac03041985ff405bda800000000000100fd56010200000000010294181a3f733a94845ac877a5c8feecf19bdb2b7671d55cf352e0cab1cf168dca0000000000ffffffff394e5ca432941a795d06c971c5b8c23639399d6cb50cb5096e676da17f0b09c90100000000ffffffff021027000000000000160014e3718cb2b07cdfcc5829cac03041985ff405bda8aa0417000000000022512046ae9024d7737f0291d1e31a2d5e3341890d677be9e1723df368f5aef312cf59024730440220745468c9cea3fce701da11ef56c8fc94c44a94dcada640eb0a9da5907a260bd2022033b2ffb9c8b176748df76e73138198f90c7faed70aab3dec03aa78963b009c9801210334903b6e2a8134171da9a363184a928894a73ede4ff0725b9739af197b6a4a100141c77db6ddd2d5f299fdb5338ef168fe3446e18d3e30f824e1c7a6d57fd935956624a1f0b668c56d1310d7ac19de9bab15e737212c3e1fcaece511d75176e701e9010000000001011d300200000000000014e3718cb2b07cdfcc5829cac03041985ff405bda80000",
  • "fee_rate": 14
}
Response samples 
application/json
{
  • "bolt11_invoice": "lnbc1....",
  • "id": "fa7c8edcd2af94876b3c6056d2845867",
  • "funded_unsigned_psbt": "70736274ff0100a60200000002dcb84258fd10be481d1fcce713d98111c1098d8a2a6a8549765442a85eb3b6190000000000ffffffffdd68df6f414c14051ac78fa26a0013674770fb48d3fa83669ed53b419dca51d70100000000ffffffff021027000000000000160014e3718cb2b07cdfcc5829cac03041985ff405bda8e2f0160000000000225120124f17b2df28ce45a0009bb8002f8ad8ee42b3fb8b3349b7fdd6d3b33a47eeab00000000000100fd56010200000000010294181a3f733a94845ac877a5c8feecf19bdb2b7671d55cf352e0cab1cf168dca0000000000ffffffff394e5ca432941a795d06c971c5b8c23639399d6cb50cb5096e676da17f0b09c90100000000ffffffff021027000000000000160014e3718cb2b07cdfcc5829cac03041985ff405bda8aa0417000000000022512046ae9024d7737f0291d1e31a2d5e3341890d677be9e1723df368f5aef312cf59024730440220745468c9cea3fce701da11ef56c8fc94c44a94dcada640eb0a9da5907a260bd2022033b2ffb9c8b176748df76e73138198f90c7faed70aab3dec03aa78963b009c9801210334903b6e2a8134171da9a363184a928894a73ede4ff0725b9739af197b6a4a100141c77db6ddd2d5f299fdb5338ef168fe3446e18d3e30f824e1c7a6d57fd935956624a1f0b668c56d1310d7ac19de9bab15e737212c3e1fcaece511d75176e701e9010000000001011d102700000000000014e3718cb2b07cdfcc5829cac03041985ff405bda80001012bc6fa1600000000002251207483eb01de713796c09aa093473548f27971daea126a6893ccdb9d9300c4630201030401000000000000"
}
Put signed transaction
Update your boost with your half-signed transaction. To be called after signing the funded_unsigned_psbt from the POST request to v1/boost-tx. You must hit this endpoint and pay the invoice to trigger the boost.


Request 
Request Body schema: application/json
required
id
required
string
The ID of your boost, from the response in the initial POST request


 
psbt
required
string
A Hex or Base64 of your PSBT, with your input signed with default SIGHASH_ALL flag


 
Responses 
200
success response


put/v1/boost-tx
Request samples 
application/json
{
  • "id": "fa7c8edcd2af94876b3c6056d2845867",
  • "psbt": "70736274ff0100a60200000002dcb84258fd10be481d1fcce713d98111c1098d8a2a6a8549765442a85eb3b6190000000000ffffffffdd68df6f414c14051ac78fa26a0013674770fb48d3fa83669ed53b419dca51d70100000000ffffffff021027000000000000160014e3718cb2b07cdfcc5829cac03041985ff405bda8e2f0160000000000225120124f17b2df28ce45a0009bb8002f8ad8ee42b3fb8b3349b7fdd6d3b33a47eeab00000000000100fd56010200000000010294181a3f733a94845ac877a5c8feecf19bdb2b7671d55cf352e0cab1cf168dca0000000000ffffffff394e5ca432941a795d06c971c5b8c23639399d6cb50cb5096e676da17f0b09c90100000000ffffffff021027000000000000160014e3718cb2b07cdfcc5829cac03041985ff405bda8aa0417000000000022512046ae9024d7737f0291d1e31a2d5e3341890d677be9e1723df368f5aef312cf59024730440220745468c9cea3fce701da11ef56c8fc94c44a94dcada640eb0a9da5907a260bd2022033b2ffb9c8b176748df76e73138198f90c7faed70aab3dec03aa78963b009c9801210334903b6e2a8134171da9a363184a928894a73ede4ff0725b9739af197b6a4a100141c77db6ddd2d5f299fdb5338ef168fe3446e18d3e30f824e1c7a6d57fd935956624a1f0b668c56d1310d7ac19de9bab15e737212c3e1fcaece511d75176e701e9010000000001011d102700000000000014e3718cb2b07cdfcc5829cac03041985ff405bda801086b0247304402201800a874626f2e88a8924ea88587b315da0be8403e0eae28b2b35bc9e147bcf202205aee1b997c65125e142c2bfd147e7e0de677b1036c96f309142888192f39e5c001210334903b6e2a8134171da9a363184a928894a73ede4ff0725b9739af197b6a4a100001012bc6fa1600000000002251207483eb01de713796c09aa093473548f27971daea126a6893ccdb9d9300c4630201030401000000000000"
}
Response samples 
application/json
{
  • "id": "fa7c8edcd2af94876b3c6056d2845867"
}
Web AI
Post AI Request
Do a single AI API call and pay for the call with a lightning micropayment. The first request returns a 402 payment required response with a bolt11 invoice in the header. You should pay this invoice and then make the same request again with the same parameters. The second request will return the result of the AI call. Currently supports OpenAI: https://platform.openai.com/docs/api-reference . Note: this is an experimental feature and the pricing structure is not well-considered. If you want to use this at scale and are particular about getting correct pricing, reach out to support@deezy.io and we'd love to chat.


Request 
header Parameters
bolt11-auth
string
A bolt-11 invoice, used as a token to authorize calls to the webai endpoint. Do not include this on your first request, but do include it on the subsequent request after paying it.


 
Request Body schema: application/json
required
request_id
required
string
A random string to identify this request. Each AI call-cycle should use a new request_id, but you should use the same one for the first and second calls in a flow.


 
provider
required
string
The AI provider to use. Currently only supports openai.


 
api_path
required
string
The endpoint to call on the AI provider. See https://platform.openai.com/docs/api-reference


 
data
required
object
Data object for the particular AI request. Depends on what endpoint you're calling. See https://platform.openai.com/docs/api-reference


 
payout_lightning_address
string
Your lightning address where you will receive earnings from usage of the app


 
Responses 
200
Successful API request


402
Payment Required


post/v1/webai
Request samples 
application/json
{
  • "request_id": "123456789abcdefg",
  • "provider": "openai",
  • "api_path": "v1/chat/completions",
  • "data": {
    },
  • "payout_lightning_address": "developer@getalby.com"
}
Response samples 
application/json
{
  • "id": "chatcmpl-123",
  • "object": "chat.completion",
  • "created": 1677652288,
  • "choices": [
    ],
  • "usage": {
    }
}