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 Circulation

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, sequence_palindrome, legacy

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.

include_top_holders
boolean

If set to true will return a list of the top 500 holders

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": {
    }
}
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",
  • "runes": [
    ],
  • "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
}