Price Management

📘

In this article

This article will cover

• General information about fiat prices for digital assets.
• How Taurus Protect gets price data and third party integrations
• How to manually update price information in Taurus Protect:
  • From the GUI
  • Via the API
• Gotchas and common pitfalls.

Introduction

This document covers how price management works in Taurus Protect. Since cryptocurrencies trade on multiple exchanges and lack a single, centralized price source, pricing typically relies on aggregating data from various providers or manually setting rates based on business needs.

Taurus Protect offers flexible pricing capabilities, allowing clients to either set cryptocurrency prices directly via API or integrate with third-party data providers like CryptoCompare to fetch real-time market rates. This document will outline how cryptocurrency pricing works in Protect, available integration options, and recommended approaches for managing reliable and consistent fiat prices.

Prices in Protect

In Taurus Protect, fiat currencies will appear in several places:

When you initially login to Protect, you will see a dashboard of assets with a total asset valuation which appears in the default fiat currency that is configured for the system. For managed services Protect customers, you can submit a service request to have the default currency updated. Generally, the base currency is set at time of environment creation.

The fiat value of a currency will appear in multiple places throughout Protect, making it easier to understand the balance of addresses, total assets under management, and more.

The dropdown above also appears in other several places like generating transfer requests. The amount you wish to transfer can be conveniently selected in fiat currency. For example, selecting 100 USD on a BTC transfer, will make a transaction request for $100 USD worth of BTC. Managed services customers can reach out to support to customize which currencies appear in this dropdown.

The price of digital assets can be a complex. The value of crypto currencies are constantly fluctuating across many different exchanges.

Taurus protect provides three ways to update prices:

1. Syncing with third party price data (currently only CryptoCompare is supported).
2. Updating prices as administrator user
3. Updating prices through the API via the Prices endpoint. This method uses private keys generated with OpenSSL. Users using these keys will not be able to login to the UI. For more information on preparing user accounts for signing, please see Signing for approval.

Third Party Price Data

Taurus Protect supports automatically syncing price data from CryptoCompare .

To enable CryptoCompare in our managed service environments please contact support. You will need to provide an API key and have a valid subscription for the CryptoCompare price feed.

Updating Price via Prices endpoint

👍

Required Permissions

Using the Prices endpoint is the recommended way to push pricing information into Taurus Protect through the available APIs.

You can update prices via a PUT request to /api/rest/v1/prices. This provides a way to update pricing information in one step, however, it requires a signature to ensure the integrity of prices. You must perform these actions through a dedicated API user account and a price updater service running in your infrastructure to programatically read prices from another source and then update protect using these credentials.

🔑

Permissions & Keys

This method of updating prices only requires the Price Updater permission.

This method requires using an Openssl EC Private Key as your signing method. Using these keys will disable this user's ability to login to the desktop and web app. A comparison of different signing methods can be found in the Signing for approval article.

This approach requires a digital signature of the price data that is being updated. Let's consider a price update request body as follows:

{
  "blockchain": "BTC",
  "currencyFrom": "BTC",
  "currencyTo": "CHF",
  "decimals": "8",
  "rate": "77500"
}

1. Sign the currency price JSON object, without any whitespace or escaped characters. For information on how to sign, see Signing for approval.

⚠️

Important

The ordering of the fields is important so that Taurus Protect can verify the signature. The cleartext bytes you sign and include in the signature field must match exactly, byte for byte, what the backend produces — no extra characters, missing fields, or differences in values. Every field must correspond precisely to the content in the API request body (see below).

{"blockchain":"BTC","currencyFrom":"BTC","currencyTo":"CHF","decimals":"8","rate":"77500"}

2. Prepare the following JSON request body, including the signature you generated in step 1, alongside the userId of your API user.

{
  "prices": [
    {
      "blockchain": "BTC",
      "currencyFrom": "BTC",
      "currencyTo": "CHF",
      "decimals": "8",
      "rate": "77500",
      "signatures": [
        {
          "signature": "I0xWyXI3L33DMZAKvvKXnlWD3GGXWh0AuL5zHD12DGp2/pR2h2MbgiQZrNGB27s/iB938UgMK1xUhbm1fNx8nw==",
          "userId": "[email protected]"
        }
      ]
    }
  ]
}

3. Send this body with a PUT request to api/rest/v1/prices

A 200 response with an empty body, {}, indicates that the price was successfully updated. This is not a change that requires approvals from admins.

Verifying

Login to the UI and go to Prices. You will then see the new price listed and the source set to api

Resetting the source

To change the source back to cryptocompare, simply send a post POST request to /api/rest/v1/changes with the following body:

{  
  "action": "update",  
  "entity": "price",  
  "changes": {  
    "blockchain": "BTC",  
    "currencyfrom": "BTC",  
    "currencyto": "CHF",  
    "decimals": "8",  
    "source": "cryptocompare.com"  
  }  
}

This will generate a pending change to be approved by an admin. After approving the change, prices for this currency pair will be automatically refreshed from CryptoCompare again.

Common Errors

Invalid signature

{
  "error": "Internal",
  "message": "an unexpected error occurred (invalid signature by user [email protected]  of: {\"blockchain\":\"BTC\",\"currencyFrom\":\"BTC\",\"currencyTo\":\"CHF\",\"decimals\":\"8\",\"rate\":\"78250\"})",
  "code": 500,
  "error_code": "bde7f732-1add-44a9-aba1-4b9d09333151"
}

If you are getting this, the signature you have passed does not match on the backend.

Invalid Parameters

{
  "error": "InvalidArgument",
  "message": "Invalid parameters - unable to set 'BTC' price with 18 decimals, when 'BTC' currency is defined with 8 decimals",
  "code": 400,
  "error_code": "E900-INVALID_PARAMETERS"
}

Ensure that the decimal value of the currency you are using is correct. You can query the Get currencyendpoint to confirm the correct decimals for a given currency.

Updating Prices via Changes Endpoint

🔒

Required Permissions

To use the changes endpoint or the GUI, the initiating user needs to have the Price Managerpermission set. Note that even users with the Admin permission will still require Price Manager in order to change prices this way.

When authenticating via the API you will need to authenticate with either Bearer Authentication) or Hmac Based Authentication.

Administrators can update Prices via the GUI or the API. Managing price this way requires the Price Manager role and is done via the changesAPI. Note that the workflow is the same for both cases:

Via API

For this example, we will manually create a BTC to CHF price rate.

1. Authenticate with the API using one of the two valid authentication methods.
2. Send a post POST request to /api/rest/v1/changes with the following body:

{
  "action": "create",
  "entity": "price",
  "changes": {
    "blockchain": "BTC",
    "currencyfrom": "BTC",
    "currencyto": "CHF",
    "decimals": "8",
    "rate": "77500"
  }
}

This will return a result ID like so

{
  "result": {
    "id": "36881"
  }
}

3. Send a POST request to /api/rest/v1/change/approveor for multiple changes, /api/rest/v1/changes/approve. You will need to be authenticated with a different user who has the Price Manager permission in order to see this change.