Make transaction

POST {{baseUrl}}/protocols/btc/transactions

Send funds to a Bitcoin recipient from a given wallet.

Define the sending wallet address via defining a from property in the body and assigning it to a string containing the address of the sending wallet. To define the sending wallet's name instead, assign the from property to an object containing the wallet property with the desired wallet's name. Add a recipient via passing a wallet name of the current vault, any valid to address, or both. If both wallet and address properties are provided in from or to, the API validates if the address resolves to the sending wallet.

POST https://api.tangany.com/custody/protocols/btc/transactions
tangany-network: testnet3

{
  "from": {
    wallet: "my-wallet"
  },
  "to": {
    "address": "tb1q0vewgvw2tpk5s8yh4e546h4ujac45z9a95hfts",
    "wallet": "my-other-wallet"
  },
  "amount": "0.000457"
}

A single recipient or a list of multiple recipients can be defined in the body. Batch multiple recipients in a single transaction to save fees compared to multiple transactions:

POST https://api.tangany.com/custody/protocols/btc/transactions
tangany-network: testnet3

{
  "from": "0x9C2E011c0CE0d75c2B62B9C5A0Ba0a7456593803",
  "list": [
    {
      "to": "bc1qc7psdze9j0r38rv8gj2kl8gysqevtqyq6v506a",
      "amount": "0.0234"
    }, {
      "to": {
        "wallet": "my-other-wallet"
      },
      "amount": "1.24"
    }, {
      "to": {
        "address": "bc1qc7psdze9j0r38rv8gj2kl8gysqevtqyq6v506a",
        "wallet": "address-verified-wallet",
      },
      "amount": "0.02340001"
    }
  ]
}

A maximum of 100 unspent transaction inputs can be employed in a transaction. This limitation can impede the max. transferable BTC amount in wallets with a high volume of unspent transaction outputs. Verify the transaction limits via the estimation endpoint to verify the actual amount of UTXO utilized in a transaction. Dust UTXOs are always excluded from basic transactions.

Call POST /protocols/btc/transactions/estimate to get a fee estimation for desired transaction configurations.

Execute a sweep transaction

A sweep transaction transfers all available funds using up to 100 unspent transaction outputs (incl. dust UTXO). The recipient will receive all transferred funds minus the transaction fees.

For wallets containing more than 100 utxo multiple sweeping calls might be required to transfer all funds to the recipient. Verify the max sweepable value and the amount of available UTXO via POST /protocols/btc/transactions/estimate. Refer to POST /protocols/btc/transactions for more information on the utxo limits.

Define the recipient via passing a wallet name of the current vault, any valid to address, or both.

Consolidate wallet outputs (including dust) by creating a sweep transaction to self. This can be used to reduce the amount of available wallet UTXO. By omitting the to recipient in the JSON body the API will assume the sending wallet as the transaction recipient (self)

POST https://api.tangany.com/custody/protocols/btc/transactions
tangany-network: mainnet

{
  "from": {
    "wallet": "func-spec",
    "address": "bc1qc7psdze9j0r38rv8gj2kl8gysqevtqyq6v506a"
  },
  "sweep": true
}

All body properties besides from are optional. Omitting the optional properties will result in a transaction of 0 BTC directed to the from address.

The endpoint processes the request in a background job and returns a status URI that reports the progress of the async operation via GET /requests/:request.

Responses

Example response body of a Running async request status: json { "status": "Running", "stage": "AwaitingTransactionConfirmation", "created": "2021-09-20T09:23:00Z", "updated": "2021-09-20T09:23:03Z", "output": { "hash": "2c27f9aeb0aa2ce827d2e4c03ebc73b7939c6824df883bcd573b729e5cf5c960" } }

Example response body of a Complete async request status: json { "status": "Completed", "stage": "transaction confirmed", "created": "2021-09-20T09:23:00Z", "updated": "2021-09-20T09:25:19Z", "output": { "confirmations": 1, "status": "confirmed", "blockHash": "0000000000000000000831ee26b770d8321e69aa4f2e390ba0367782a765ec6b", "blockNr": 689000, "receivedTime": "2021-06-28T03:42:18.000Z", "totalInput": "0.0290429", "totalOutput": "0.02898479", "fees": "0.00005811", "hash": "f1793c0907b3110a210652ba1980b45ed0178cb74fd98a002a2885b52dc6a9e9" } }

Request Body

{"from"=>{"wallet"=>"{{wallet}}"}, "to"=>{"wallet"=>"my-other-wallet"}, "amount"=>"0.0023"}

HEADERS

Key	Datatype	Required	Description
`tangany-version`	number		(Required) Default header that directs the request towards desired Tangany Custody Api version (e.g `2` directs to Tangany Custody APi v2).

Accepts supported network enums. Defaults to mainnet when omitted from the call.

Supported networks: mainnet, testnet3.

Example: testnet3 | | tangany-tx-confirmations | number | | (Optional header) Defines a secure amount of block confirmations required to consider a bitcoin transaction as valid.

Accepts positive integers. Defaults to 1.

Bitcoin transactions are usually considered final after 6 network confirmations. | | tangany-utxo-confirmations | number | | (Optional header) Defines a secure amount of block confirmations required for Bitcoin balance outputs ("UTXO", "coins") to consider the input as valid and consequently to be included in the total wallet balance calculation or a new transaction.

Accepts positive integers. Defaults to 1.

The inclusion of unconfirmed outputs via 0 bears the risk of the posthumous invalidation of own wallet transactions by the parent utxo sending party. They can e.g. be used for retrieving total BTC wallet balances including the pending UTXO.

When present, the asynchronous transaction will be identified by the provided ID.

The API rejects all but the first request with a given request ID. This way, you can make sure that a given action (e.g. a transaction) will be executed only once.

A client-generated ID can also be used to deterministically recover a missed API response, for example in the event of a gateway timeout or loss of connection.

The API responds with a 409 Conflict status when a given ID has already been used. See GET /requests/:request for more information.

The value must be between 1 and 36 characters and contain only alphanumeric characters or dashes.