The Upvest Blockchain API

A multi-protocol blockchain API for building blockchain-interacting applications.

Get Started     Tutorial     API Reference

Transactions and Fees

Learn how to conduct transactions on the blockchain

You can make transactions on any of the supported blockchain protocols. A transaction is executed on behalf of a user and requires the user to have sufficient funds in their wallet in order to pay the amount of the asset being sent, as well as the transaction fee (with the exception of ERC-20 tokens where Upvest pre-funds the user’s wallet in order to cover the transaction fee).

Within the Upvest platform, all quantities are denominated in the smallest unit of the respective currency. In the example of Ether, this would be Wei, in the example of Bitcoin this would be Satoshi. This should be taken into consideration when calculating amounts and fees, for example converting from Gwei to Wei.


Calculating Fees

When making a transaction via the Upvest API, a single ‘fee’ parameter is provided. The value for this will vary depending on the blockchain and assets being transacted. We provide common examples for Ether and ERC-20 transfers below.

Calculating the fee for Ether and ERC-20 token transfers

Ethereum transaction fees are composed of two components:

  • Gas Price (the amount, in Ether, to pay per unit of Gas)
  • Gas Limit (the maximum amount of Gas to pay for the transaction)

ERC-20 transaction pre-funding

Many users will only keep ERC-20 tokens in their wallets, and transferring these out of their wallets would normally mean having to put some Ether into the wallet in order to pay the transaction Gas fee. Due to the undesirable complexity involved, Upvest provides a mechanism to automatically pre-fund any wallet making an ERC-20 transaction with the amount of Ether needed to pay the Gas fee.

The Gas Price to pay is commonly the determining factor for how quickly your transaction gets processed (i.e. confirmation), and the value will vary depending on how many transactions are pending to be processed on the blockchain. The current Gas Price to pay for desired confirmation within certain time frames (or a given number of blocks) can be tricky to estimate, and Upvest's Fee API for Ethereum can help with this. The assisting guide Transaction Fee Estimations for Ethereum and Bitcoin explains the process in detail.

The Gas Limit will vary depending on the transaction type being made. For example, a standard Ethereum transaction (including an Ether transfer) costs a fixed Gas amount of 21000. Smart contracts calls (including ERC-20) will have varying Gas Limits depending on how much gas they consume.

The basic calculation is:

fee = ({smart_contract_gas_limit} + 21000) * gas_price_in_wei

A sample fee calculation for an ERC-20 token transfer whose smart contract has a Gas Limit of 300,000 is provided below:

ropsten_gas_price_in_gwei = 3.5;
gwei_to_wei = 1e9;
tx.fee = (300000 + 21000) * ropsten_gas_price_in_gwei * gwei_to_wei;

As you can see, the total Gas Limit is the contract’s limit (300,000) plus the standard Ethereum transaction cost (21,000) for a total of (321,000) Gas. Multiplied by today’s chosen Gas Price (3.5 Gwei), this results in a fee of 1123500000000000 Wei or 0.0011235 Ropsten ETH. Note the conversion of the Gas Price from Gwei to Wei (this Eth Converter may come in handy). For an Ether-only transfer, the Gas Limit would simply be 21,000.

Calculating the fee for Bitcoin transactions

Calculating fees for Bitcoin transactions involves a slightly more complicated process including the number of transaction inputs (UTXO) and outputs, the number of bytes they represent, and the cost-per-byte and is detailed well in this guide.

Upvest also provides a Fee API for Bitcoin which helps estimate how many Satoshis per virtual byte to pay. The assisting guide Transaction Fee Estimations for Ethereum and Bitcoin explains the process in detail.

Here are a few more useful resources:


Making Transactions

In order to create a transaction, we first need to create a user and a wallet belonging to the user, via the Upvest API.

Ethereum Example

After funding the wallet with Ether, a transaction can be conducted, specifying the source Wallet ID, the recipient Ethereum address, the Asset ID of the asset to transfer (Ropsten Ether in the example below), the quantity of the asset to transfer and the fee amount Transactions and Fees:

A sample transaction payload is shown below:

{
"password":"user_password",
"wallet_id":"8a81bc7d-5b91-43f8-97d8-339a687b8c09",
"asset_id":"deaaa6bf-d944-57fa-8ec4-2dd45d1f5d3f",
"quantity":"565775720002747422",
"fee":"216300000000000",
"recipient":"0x5Ba27c6227F809C650a9C2bEf9D6705b9E9d6fE7",
"async":true
}

Bitcoin Example

After funding the wallet with Bitcoin, a transaction can be conducted, specifying the source Wallet ID, the recipient Bitcoin address, the Asset ID of the asset to transfer (Testnet Bitcoin in the example below), the quantity of the asset to transfer, the fee amount Transactions and Fees and, for Bitcoin only, the desired Unspent Transaction Outputs (UTXOs) to redeem in the inputs parameter.

Prior to making a Bitcoin transaction, you must establish which UTXOs are available to the user's wallet, and select sufficient UTXOs to cover the amount and fee for the transaction. These can be obtained via the utxos endpoint. Any remaining Bitcoin after subtracting the amount and fee will be returned to the sending wallet's address (i.e. change address in Bitcoin parlance. The Upvest API does not yet support the creation of new change addresses.

Bitcoin Balances

The UTXOs endpoint will return the value of each UTXO, which can be used to calculate the balance of the queried wallet. In the example below, the wallet has a balance of 3749832 Satoshi or 0.03749832 BTC

{
  "utxos": [
    {
      "index": 1,
      "tx": "0e41f8425b37a62c77a14284c5f9981909156b24dae5d2badb127c08b84e0739",
      "type": "P2PKH",
      "value": 100000
    },
    {
      "index": 0,
      "tx": "0e41f8425b37a62c77a14284c5f9981909156b24dae5d2badb127c08b84e0739",
      "type": "P2PKH",
      "value": 3649832
    }
  ]
}

A sample transaction payload with our selected UTXO to use is shown below:

{
"password":"user_password",
"wallet_id":"1577f4df-5186-453b-8929-103c14c5c532",
"asset_id":"a3c18f74-935e-5d75-bd3c-ce0fb5464414",
"quantity":"100000",
"fee":"600",
"recipient":"n2iQsck5ULT5HNVbYH57WpK8tvEZY7GYya",
"async":true,
"inputs":[
    {
      "index": 0,
      "tx": "c9a6e1c674aade441935d4a7510d113c70647375aa4f4b859ade7ba58ae4c0a4",
      "type": "P2PKH",
      "value": 3750432
    }
  ]
}

Transaction UUID

The response will return a Transaction ID that can be used to query that transaction's status. The transaction payload will be validated and broadcast to the blockchain.


Transaction Statuses

Ethereum Only

Note that at the moment, only Ethereum transactions have their transactions statuses updated. Bitcoin transactions are processed, but the internal transaction status will stay as QUEUED. You will need to use other tools to monitor the Bitcoin blockchain for the status of your Bitcoin transactions (using the transaction hash returned).

Within the Upvest platform, transactions can have one of the following statuses:

Status
Description

QUEUED

The default state when initially creating a transaction during the initial API call. This indicates that this transaction is waiting to be picked up by a background worker.

PROCESSING

A background worker has started to process this transaction.

FUNDING

An auxiliary funding transaction is being initiated (this only applies to non-Ether transactions).

FUNDED

An auxiliary funding transaction was successful (this only applies to non-Ether transactions).

BROADCASTING

The transaction is being announced to the blockchain network nodes.

BROADCASTED

The transaction was successfully announced to the blockchain network nodes.

PENDING

The transaction is "pending" / "in the mempool", i.e. known to (some) blockchain network nodes, and awaiting inclusion/mining into a block.

CONFIRMING

The transaction was mined into a block, but not enough subsequent blocks have yet been mined to consider that transaction "safe" / confirmed.

CONFIRMED

The transaction was mined into a block and enough subsequent blocks have been mined to consider that transaction "safe" / confirmed.

FAILED

The transaction was mined into a block, but the execution of its smart contract code failed. Several reasons are possible, most notably "out of gas". The transaction is still included in a block because its gas is still awarded to the miner who attempted to execute it.

REJECTED

The transaction was mined into a block but was rejected during the execution of its smart contract code. Several reasons are possible, most notably Solidity's require() assertions not being satisfied. The transaction is still included in a block because it's gas is still awarded to the miner who attempted to execute it.

UNPROCESSABLE

An unrecoverable error occurred which prevents us from getting this transaction onto the blockchain. We have given up (or the customer requested us not to retry).

RETRYING

A temporary/recoverable error occurred, and this transaction was re-queued as to try getting this transaction onto the blockchain at a later time. This state is more or less equivalent to QUEUED, but its name is more telling.

Updated about a month ago



Transactions and Fees


Learn how to conduct transactions on the blockchain

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.