Deezy API (1.0.0)

Deezy Rare Satoshi Circulation and Hunting API

Download OpenAPI description

swagger.json

swagger.yaml

Servers

Mock server

https://docs.deezy.io/_mock/swagger/

Mainnet

https://api.deezy.io/

Testnet

https://api-testnet.deezy.io/

Sat Circulation

Operations

Sat Hunting

Operations

Scan a UTXO or Address for Special Sats

Request

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.

Bodyapplication/jsonrequired

One of:

utxo_to_scanstringrequired

The UTXO to scan for special satoshis.

Example: "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b:0"

extractboolean

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

Example: true

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

Example: ["bc1ptjcfjm8f7gz8umrh0sg3ve8ewq3gm0q9m7khhplny8u7m0nvqf8s0ym0zh","bc1ptnadrqyv2862egv6ywanrpllknxw7tks2j9ddlwll9c8ada492cqy67rqd","bc1pgfyhzsjmkdtknrh3puzartyxjyztkpm7pfgmuleekj7akksr06lqvmxz8g"]

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

Example: ["bc1pdeyrsp2zyevlyenmqv4n240ww9hppf54x4eem5p473lqxh6jepts0wg28y","bc1pd7u90a2xvq3nkh4jdtym35uwa8h5xz9xhtcjkj7nj9vdn328hjvsctgu5r","bc1p3j5hrnxw7nkc0367pfygggf4pwata98zs7u75jcqp8cxklzak7yq9jfk9z"]

extraction_fee_ratenumber

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

Example: 10

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

Example: [["omega","prime"],["omega"],["alpha","prime"],["alpha"],["block_78"],["vintage_nakamoto"],["pizza"]]

included_tagsArray of strings

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

Example: [["omega","prime"],["omega"],["alpha","prime"],["alpha"],["block_78"],["vintage_nakamoto"],["pizza"]]

min_tag_sizesobject

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.

Example: {"block_78":100,"vintage_nakamoto":300}

max_tag_agesobject

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.

Example: {"alpha":2009,"omega":2010}

tag_limitsobject

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.

Example: {"alpha":10,"omega":15}

tag_by_addressobject

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.

Example: {"uncommon":"address123","omega":"address345"}

split_triggerstring

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.

Example: "NEVER"

split_target_size_satsinteger

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

Example: 100000000

withdraw_addressstring

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

Example: "bc1q2utnxf5d4y2vqmly5w675dqxtgd0fqhnezmq52"

withdraw_size_satsinteger

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

Example: 100000000

split_special_rangesboolean

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.

Example: false

curl -i -X POST \
  https://docs.deezy.io/_mock/swagger/v1/sat-hunting/scan \
  -H 'Content-Type: application/json' \
  -H 'x-api-token: YOUR_API_KEY_HERE' \
  -d '{
    "address_to_scan": "bc1qy3c3vn2pfrmk8t5qt2apqqxx48l80senpfmqqh",
    "extract": true,
    "special_sat_addresses": [
      "bc1ptjcfjm8f7gz8umrh0sg3ve8ewq3gm0q9m7khhplny8u7m0nvqf8s0ym0zh",
      "bc1ptnadrqyv2862egv6ywanrpllknxw7tks2j9ddlwll9c8ada492cqy67rqd",
      "bc1pgfyhzsjmkdtknrh3puzartyxjyztkpm7pfgmuleekj7akksr06lqvmxz8g"
    ],
    "regular_funds_addresses": [
      "bc1pdeyrsp2zyevlyenmqv4n240ww9hppf54x4eem5p473lqxh6jepts0wg28y",
      "bc1pd7u90a2xvq3nkh4jdtym35uwa8h5xz9xhtcjkj7nj9vdn328hjvsctgu5r",
      "bc1p3j5hrnxw7nkc0367pfygggf4pwata98zs7u75jcqp8cxklzak7yq9jfk9z"
    ],
    "extraction_fee_rate": 10,
    "excluded_tags": [
      [
        "omega",
        "prime"
      ],
      [
        "omega"
      ],
      [
        "alpha",
        "prime"
      ],
      [
        "alpha"
      ],
      [
        "block_78"
      ],
      [
        "vintage_nakamoto"
      ],
      [
        "pizza"
      ]
    ],
    "included_tags": [
      [
        "omega",
        "prime"
      ],
      [
        "omega"
      ],
      [
        "alpha",
        "prime"
      ],
      [
        "alpha"
      ],
      [
        "block_78"
      ],
      [
        "vintage_nakamoto"
      ],
      [
        "pizza"
      ]
    ],
    "min_tag_sizes": {
      "block_78": 100,
      "vintage_nakamoto": 300
    },
    "max_tag_ages": {
      "alpha": 2009,
      "omega": 2010
    },
    "tag_limits": {
      "alpha": 10,
      "omega": 15
    },
    "tag_by_address": {
      "uncommon": "address123",
      "omega": "address345"
    },
    "split_trigger": "NEVER",
    "split_target_size_sats": 100000000,
    "withdraw_address": "bc1q2utnxf5d4y2vqmly5w675dqxtgd0fqhnezmq52",
    "withdraw_size_sats": 100000000,
    "split_special_ranges": false
  }'

Responses

ID of the scan operation

Bodyapplication/json

idstring

An ID of the scan operation. Use the GET endpoint with this ID to lookup the result. The time to complete the scan depends on the size of the UTXO being scanned and can range from a few seconds to a few minutes.

Example: "20a27d48e7ae0db029a01b1fd06fd6d8"

Response

application/json

{
  "id": "20a27d48e7ae0db029a01b1fd06fd6d8"
}

Get Result of UTXO or Address Scan

Request

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

Path

idstringrequired

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

curl -i -X GET \
  'https://docs.deezy.io/_mock/swagger/v1/sat-hunting/scan/{id}' \
  -H 'x-api-token: YOUR_API_KEY_HERE'

Responses

Rare Sat Info for the Provided UTXO or address

Bodyapplication/json

statusstring

The status of the scan operation - PENDING, PROCESSING, or COMPLETED

Example: "COMPLETED"

utxostring

The UTXO that was scanned for special satoshis

Example: "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b:0"

addressstring

The address that was scanned for special satoshis

Example: "bc1qy3c3vn2pfrmk8t5qt2apqqxx48l80senpfmqqh"

runesArray of objects

A list of Runes identified in the provided UTXO or address. If no Runes were found, this will be an empty array.

satributesArray of objects

A list of special satoshis identified in the provided UTXO or address. If no special sats were found, this will be an empty array.

extraction_psbtstring

A base64-encoded unsigned PSBT that extracts the special sats to addreses of your choice. Only returned if "extract" is true in the request body. If no special sats were identified, this will be null. WARNING: You should run additional verification locally to check that the fee rate is reasonable and that all outputs are to addresses you control before signing and broadcasting.

Example: "cHNidP8BAHECAAAAAeJQY2VLRtutKgQYFUajEKpjFfl0Uyrm6x23OumDpe/4AQAAAAD/////AkxREgEAAAAAFgAUv6pTgbKHN60CZ+RQn5yOuH6c2WiA8PoCAAAAABYAFJDbOFU0E6zFF/M+g/AKDyqI2iUaAAAAAAABAOsCAAAAAAEBbxqXgEf9DlzcqqNM610s5pL1X258ra6+KJ22etb7HAcBAAAAAAAAAAACACT0AAAAAAAiACC7U1W0iJGhQ6o7CexDh5k36V6v3256xpA9/xmB2BybTFZdDQQAAAAAFgAUKp2ThzhswyM2QHlyvmMB6tQB7V0CSDBFAiEA4Md8RIZYqFdUPsgDyomlzMJL9bJ6Ho23JGTihXtEelgCIAeNXRLyt88SOuuWFVn3IodCE4U5D6DojIHesRmikF28ASEDHYFzMEAxfmfq98eSSnZtUwb1w7mAtHG65y8qiRFNnIkAAAAAAQEfVl0NBAAAAAAWABQqnZOHOGzDIzZAeXK+YwHq1AHtXQEDBAEAAAAAAAA="

excluded_tagsArray of strings

The value used for excluded_tags in the scan.

Example: [["omega"],["alpha"],["block_78"],["vintage_nakamoto"],["pizza"]]

included_tagsArray of strings

The value used for included_tags in the scan.

Example: [["omega"],["alpha"],["block_78"],["vintage_nakamoto"],["pizza"]]

min_tag_sizesobject

The value used for min_tag_sizes in the scan.

Example: {"block_78":100,"vintage_nakamoto":300}

tag_limitsobject

The value used for tag_limits in the scan.

Example: {"alpha":10,"omega":15}

tag_by_addressobject

The value used for tag_by_address in the scan.

Example: {"uncommon":"address123","omega":"address345"}

split_triggerstring

The value used for split_trigger in the scan.

Example: "NEVER"

split_target_size_satsinteger

The value used for split_target_size_sats in the scan.

Example: 100000000

withdraw_addressstring

The value used for withdraw_address in the scan.

Example: "bc1q2utnxf5d4y2vqmly5w675dqxtgd0fqhnezmq52"

withdraw_size_satsinteger

The value used for withdraw_size_sats in the scan.

Example: 100000000

withdraw_successboolean

If withdraw_address was provided, denotes if a withdrawal output was sucessfully created.

Example: true

split_special_rangesboolean

The value used for split_special_ranges in the scan.

Example: true

Response

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": {
    "block_78": 100,
    "vintage_nakamoto": 300
  },
  "tag_limits": {
    "alpha": 10,
    "omega": 15
  },
  "tag_by_address": {
    "uncommon": "address123",
    "omega": "address345"
  },
  "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

Request

Get the status of scanning operations.

Query

limitinteger

The number of requests to return. Defaults to 100.

offsetinteger

The offset of requests to return. Defaults to 0.

curl -i -X GET \
  'https://docs.deezy.io/_mock/swagger/v1/sat-hunting/scans?limit=0&offset=0' \
  -H 'x-api-token: YOUR_API_KEY_HERE'

Responses

Scan requests for the Provided API User

Bodyapplication/jsonArray [

request_idstring

The request_id for the scan

Example: "358c7d411b3491cf9ed5d65d984a6415"

statusstring

The status of the scan (can be "PENDING", "PROCESSING", or "COMPLETE")

Example: "PENDING"

]

Response

application/json

[
  {
    "request_id": "358c7d411b3491cf9ed5d65d984a6415",
    "status": "PENDING"
  }
]

Get Rarity Tags

Request

Get list of recognized rarity tags; these values can be used for the excluded_tags and included_tags parameters in the scan request.

curl -i -X GET \
  https://docs.deezy.io/_mock/swagger/v1/sat-hunting/tags \
  -H 'x-api-token: YOUR_API_KEY_HERE'

Responses

Currently recognized rarity tags for sat scanning

Bodyapplication/json

rarity_tagsArray of strings

Name of each rarity_tag

Example: "mythic"

Response

application/json

{
  "rarity_tags": "mythic"
}

Get User Limits

Request

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.

Headers

x-api-tokenstringrequired

API token for the user

curl -i -X GET \
  https://docs.deezy.io/_mock/swagger/v1/sat-hunting/user/limits \
  -H 'x-api-token: string'

Responses

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.

Bodyapplication/json

payment_addressstring

Payment address of the user

Example: "1bc1q..."

amountnumber

Amount limit for the user

Example: 97666993630

unitstring

Unit of the amount, typically 'sats'

Example: "sats"

daysnumber

Number of days for the limit

Example: 30

subscription_costnumber

Subscription cost for the user

Example: 100000000

one_time_costnumber

Subscription cost for the user in satoshis per 1 BTC of scan volume

Example: 200000

user_volumenumber

User consumed volume for the current period

Example: 97666993631

remaining_volumenumber

User remaining volume

Example: 97666993631

Response

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)

Request

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.

Query

group_bystring

Group the results by a specified attribute. Valid values include: 'year', 'month', 'epoch', 'period', or 'block'.

days_agointeger

Filter the results to include data from the specified number of days ago. Defaults to 30 days.

Default 30

curl -i -X GET \
  'https://docs.deezy.io/_mock/swagger/v1/sat-hunting/earnings?days_ago=30&group_by=string' \
  -H 'x-api-token: YOUR_API_KEY_HERE'

Responses

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

Bodyapplication/json

summaryArray of objects

The summary of earnings.

Example: [{"rarity_tags":["omega"],"count":100,"group_by_value":"2023-03","floor_price_sats":1000,"total_value_sats":100000},{"rarity_tags":["uncommon","block_9"],"count":1,"group_by_value":"2009-04","floor_price_sats":250000,"total_value_sats":250000}]

group_bystring

The group_by parameter used in the query.

days_agointeger

The days_ago parameter used in the query.

Response

application/json

{
  "summary": [
    { … },
    { … }
  ],
  "group_by": "string",
  "days_ago": 0
}

Deezy API (1.0.0)

Sat Circulation

Sat Hunting

Scan a UTXO or Address for Special Sats

Request

Responses

Was this helpful?

Get Result of UTXO or Address Scan

Request

Responses

Was this helpful?

Get status of UTXO Scans

Request

Responses

Was this helpful?

Get Rarity Tags

Request

Responses

Was this helpful?

Get User Limits

Request

Responses

Was this helpful?

Get Earnings Summary (DRAFT - not implemented yet)

Request

Responses

Was this helpful?

Deezy API (1.0.0)

Sat Circulation

Sat Hunting

Scan a UTXO or Address for Special Sats

RequestExpand all

Responses

Was this helpful?

Get Result of UTXO or Address Scan

Request

Responses

Was this helpful?

Get status of UTXO Scans

Request

Responses

Was this helpful?

Get Rarity Tags

Request

Responses

Was this helpful?

Get User Limits

Request

Responses

Was this helpful?

Get Earnings Summary (DRAFT - not implemented yet)

Request

Responses

Was this helpful?

Request