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). |
Supports only major versions. |
| tangany-network
| string | | (Optional header) Defines the network to operate in - in the Bitcoin context.
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.
Example: 12
|
| tangany-request-id
| string | | (Optional header) A client provided request ID / idempotency key for the asynchronous transaction
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.
Defaults to a randomly generated value when omitted. |
| Content-Type
| string | | |
| Accept
| string | | |