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

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. Upvest has the option to pre-fund 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. For Ether, this is Wei. 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: How To Save On Gas? 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](http://eth-converter.com/) may come in handy). For an Ether-only transfer, the Gas Limit would simply be `21,000`.

---

## Making Transactions
In order to create a [transaction](https://doc.upvest.co/reference#kms_transaction_create), we first need to [create a user](https://doc.upvest.co/reference#tenancy_user_create) 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](doc:transactions-and-fees#section-calculating-the-fee-amount-for-ether-and-erc-20-token-transfers):

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
}

📘

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

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.