Overview

The upcoming API Version 1.4 release on April 13, 2020 may break your current Fireblocks API implementation. Read the following information carefully to take the necessary actions.

The new features in this version are:

• The Confirmation Policy
• Improved Exchange Transaction Tracking

Learn more about the new features.

We have also made a few changes and additions to API messages. Learn more about the API changes.

Features

The Confirmation Policy

The confirmation policy allows users to control how many confirmations are required for an incoming transaction to get cleared. When a transaction gets cleared:

• It is accounted for in the “available balance”
• Its outputs (For UTXO) are spendable

Until a transaction gets cleared, its amount is accounted for with a balance property called “pending balance”.

The default confirmation policy is:

• All deposits require a single confirmation (including vault-to-vault transfers)

The default confirmation policy can be overridden by a user-defined policy, which operates on a first-match basis rule set, defined by the source, destination, amount (USD or native-based), and asset type. Currently, there is no way to view or edit the policy. If you wish to set a user-defined policy, submit a request to Fireblocks Support.

See this article for more details.

What’s new?

• User-defined confirmations for all deposits (currently an incoming transaction is always accounted for in the balance after one confirmation)
• The pending balance (currently no ability to view incoming transaction amounts)
• We are deprecating the CONFIRMED status and introducing a new COMPLETED status that indicates a successfully cleared transaction (transaction is cleared as soon as its status switches to COMPLETED).

Improved Exchange Transaction Tracking

Improved Exchange Transaction Tracking increases the depth of feedback for inbound and outbound exchange transfers in the form of better status granularity and accuracy.

The COMPLETED status provides feedback on when a deposit to an exchange is cleared on the exchange side.

In addition, there are new pending and failure statuses. View the full list of transaction statuses.

Consistent API Messages and Responses (a few minor changes and additions to API messages)

Push messages via the Push API are being updated to be the same as REST API responses. The two APIs will align and be 1-to-1 in terms of returned data. Until now there have been several mismatches between the two, which sometimes led to confusion and ambiguity. This is no longer an issue with the two APIs speaking the same language.

Complete API Changes Overview

New API fields

We have added a couple of API transaction information fields:

• Substatus (subStatus): A more detailed status level for pending, successful, and failure statuses. The subStatus field replaces the deprecated failureReason field. You can see the full list of statuses here.
• Pending Balance (pending): The cumulative balance of all transactions pending to be cleared.

The fields were added to the TransactionDetails object which is returned:

• In the response of the following REST API endpoints:
  • Retrieve Transactions Info
  • Get a specific Transaction
  • Create a New Transaction
• As the body of the following webhook (Push API) notifications:
  • TX_CREATED
  • TX_UPDATED

Status changes

• The CONFIRMED status is deprecated.
• The new COMPLETED status indicates a successfully completed transaction (both for inbound and outbound transactions). For incoming transactions, this status also indicates that the transaction is cleared.
• The rejection of a transaction on a mobile device or a co-signer was previously marked as REJECTED. This state is now marked as CANCELLED with a REJECTED_BY_USER substatus.

Push API Changes

We have updated push messages from the Push API to be the same as REST API responses.

The body of TX_CREATED and TX_UPDATED now use the TransactionDetails structure:

• ֿtxId is now id
• fee is now networkFee
• totalAmount is now amount
• Added requestedAmount
• dest is now destination
• Added destinationAddress field, which replaces the address field previously nested in dest
• Added destinationTag field, which replaces the tag field previously nested in dest
• Added destinationAddressDescription field, which replaces the addressDescription field previously nested in dest
• Removed numOfConfirmations
• source and destination now use the TransferPeerPath structure:
  • The UNMANAGED_WALLET_CONTAINER type is now divided into the INTERNAL_WALLET type and the EXTERNAL_WALLET type, for internal and external wallets, respectively.