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)

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.

ERC-20 transaction pre-funding

Many users will only keep ERC-20 tokens in their wallets, however as we’ve seen above, 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 of this, 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.

Calculating the fee for Bitcoin transactions

Calculating fees for Bitcoin transactions involves a slightly more complicated process including the number transaction inputs (UTXO) and outputs, the number of bytes they represent, and the cost-per-byte, and is better left to more in-depth guides. However, here are a few 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:


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:

      "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.

General Purpose Signing Interface

The General Purpose Signing Interface (GPSI) is an endpoint that gives you complete flexibility to craft the payload you wish to have signed by a particular user's private key. This allows you to sign arbitrary payloads for performing any action on the blockchain, including interacting with any smart contract functionality.

GPSI is used by building the payload and then sending the hash of the payload to be signed with a given user's private key. The returned signature (example below) can then be broadcast to the network together with the payload.

  "big_number_format": "base64_bigendian",
  "algorithm": "ECDSA",
  "curve": "secp256k1",
  "public_key": {
    "x": "YY0cw9hcCzkZCa0huZAMToIsJ3cGVbl/nqbKtuQduts=",
    "y": "Rn4cVSwDcBOL79je/9RpUAsEg/PZ6LcbUbc3qiI2JTg="
  "r": "Is/lCtLfXzY3A3+sO9+EW/m92BB0UbQsa+uWA8Oj7Rk=",
  "s": "KUmIX4vwIsQGsnhGzV9jhsCKoDijILGtln3ICDmbNRw=",
  "recover": 1

When validating the signature for Ethereum, remember to take EIP-155 into consideration when calculating the v parameter.

Code Examples

Code examples for using GPSI are available here.

Updated 8 days 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.