distributeasset

distributeasset "target_asset" distribution_amount ( {"distribution_asset":"str","min_dust_threshold":n,"snapshot_height":n,"dry_run":bool,"max_recipients":n,"remainder_strategy":"str","fee_rate":n} ) Distribute an asset or TSC pro-rata to all holders of a specified asset. Scans the UTXO set to find all holders, then creates a transaction paying each holder proportionally based on their holdings. IMPORTANT: This operation can take 10-60 seconds for full UTXO set scan. Arguments: 1. target_asset (string, required) Asset ID (hex) or ticker whose holders will receive distribution 2. distribution_amount (numeric or string, required) Total amount to distribute. For TSC: BTC amount. For assets: raw units. 3. options (json object, optional) { "distribution_asset": "str", (string, optional, default="TSC") Asset to distribute (TSC or asset_id/ticker) "min_dust_threshold": n, (numeric, optional, default=1000) Minimum payment (satoshis for TSC, raw units for assets) "snapshot_height": n, (numeric, optional) Block height for UTXO snapshot "dry_run": bool, (boolean, optional, default=false) Preview distribution without broadcasting "max_recipients": n, (numeric, optional, default=1000) Maximum recipients per transaction "remainder_strategy": "str", (string, optional, default="refund") 'refund' or 'topup' "fee_rate": n, (numeric, optional) Fee rate in sat/vB } Result: { (json object) "txid" : "hex", (string, optional) Transaction ID (only if dry_run=false) "hex" : "hex", (string, optional) Transaction hex (only if dry_run=false) "fee" : n, (numeric, optional) Transaction fee (only if dry_run=false) "asset_change" : n, (numeric, optional) Asset change returned (only for asset distributions) "distribution_asset" : "str", (string) Asset distributed "total_distributed" : n, (numeric) Actual amount distributed "remainder" : n, (numeric) Undistributed amount due to rounding "recipient_count" : n, (numeric) Number of recipients "filtered_count" : n, (numeric) Recipients filtered by dust "utxos_scanned" : n, (numeric) Total UTXOs scanned "utxos_with_asset" : n, (numeric) UTXOs containing target asset "recipients" : [ (json array) Distribution list (filtered recipients excluded) { (json object) "address" : "str", (string) Recipient address "holdings" : n, (numeric) Asset units held "amount" : n (numeric) Distribution amount }, ... ] } Examples: > bitcoin-cli distributeasset "GOLD" 1.0 '{"dry_run":true}'

Signature

distributeasset(target_asset: string, distribution_amount: any, options?: object) → any

Code samples

curl --user "$RPC_USER:$RPC_PASS" \
  --data-binary '{"jsonrpc":"1.0","id":"docs","method":"distributeasset","params":["\"<target_asset>\"","\"<distribution_amount>\"",{}]}' \
  -H 'content-type: text/plain;' \
  http://127.0.0.1:8332/

bitcoin-cli distributeasset "GOLD" 1.0 '{"dry_run":true}'

import requests
r = requests.post(
    "http://127.0.0.1:8332/",
    auth=("$RPC_USER", "$RPC_PASS"),
    json={
        "jsonrpc": "1.0",
        "id": "docs",
        "method": "distributeasset",
        "params": ["\"<target_asset>\"", "\"<distribution_amount>\"", {}],
    },
    timeout=30,
)
print(r.json())

const res = await fetch("http://127.0.0.1:8332/", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "authorization": "Basic " + btoa(`${process.env.RPC_USER}:${process.env.RPC_PASS}`),
  },
  body: JSON.stringify({
    jsonrpc: "1.0",
    id: "docs",
    method: "distributeasset",
    params: ["\"<target_asset>\"","\"<distribution_amount>\"",{}],
  }),
});
console.log(await res.json());

Parameters

Name	Type	Req.	Description
target_asset	`string`	yes	Asset ID (hex) or ticker whose holders will receive distribution
distribution_amount	`number \| string`	yes	Total amount to distribute. For TSC: BTC amount. For assets: raw units.
options	`object`	—	{ "distribution_asset": "str", (string, optional, default="TSC") Asset to distribute (TSC or asset_id/ticker) "min_dust_threshold": n, (numeric, optional, default=1000) Minimum payment (satoshis for TSC, raw units for assets) "snapshot_height": n, (numeric, optional) Block height for UTXO snapshot "dry_run": bool, (boolean, optional, default=false) Preview distribution without broadcasting "max_recipients": n, (numeric, optional, default=1000) Maximum recipients per transaction "remainder_strategy": "str", (string, optional, default="refund") 'refund' or 'topup' "fee_rate": n, (numeric, optional) Fee rate in sat/vB }

Result

Type: any

{ (json object) "txid" : "hex", (string, optional) Transaction ID (only if dry_run=false) "hex" : "hex", (string, optional) Transaction hex (only if dry_run=false) "fee" : n, (numeric, optional) Transaction fee (only if dry_run=false) "asset_change" : n, (numeric, optional) Asset change returned (only for asset distributions) "distribution_asset" : "str", (string) Asset distributed "total_distributed" : n, (numeric) Actual amount distributed "remainder" : n, (numeric) Undistributed amount due to rounding "recipient_count" : n, (numeric) Number of recipients "filtered_count" : n, (numeric) Recipients filtered by dust "utxos_scanned" : n, (numeric) Total UTXOs scanned "utxos_with_asset" : n, (numeric) UTXOs containing target asset "recipients" : [ (json array) Distribution list (filtered recipients excluded) { (json object) "address" : "str", (string) Recipient address "holdings" : n, (numeric) Asset units held "amount" : n (numeric) Distribution amount }, ... ] }

Source: services/core-node/bcore/src/wallet/rpc/assets.cpp:8980

C++ symbol: distributeasset

Code samples

curl --user "$RPC_USER:$RPC_PASS" \
  --data-binary '{"jsonrpc":"1.0","id":"docs","method":"distributeasset","params":["\"<target_asset>\"","\"<distribution_amount>\"",{}]}' \
  -H 'content-type: text/plain;' \
  http://127.0.0.1:8332/

bitcoin-cli distributeasset "GOLD" 1.0 '{"dry_run":true}'

import requests
r = requests.post(
    "http://127.0.0.1:8332/",
    auth=("$RPC_USER", "$RPC_PASS"),
    json={
        "jsonrpc": "1.0",
        "id": "docs",
        "method": "distributeasset",
        "params": ["\"<target_asset>\"", "\"<distribution_amount>\"", {}],
    },
    timeout=30,
)
print(r.json())

const res = await fetch("http://127.0.0.1:8332/", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "authorization": "Basic " + btoa(`${process.env.RPC_USER}:${process.env.RPC_PASS}`),
  },
  body: JSON.stringify({
    jsonrpc: "1.0",
    id: "docs",
    method: "distributeasset",
    params: ["\"<target_asset>\"","\"<distribution_amount>\"",{}],
  }),
});
console.log(await res.json());