NAV Navbar
Python JavaScript

Introduction

Welcome to the Fireblocks developer page! Fireblocks provides a REST API that enables you to manage your workspace as well as fully automate your transaction flow and a webhook that provides you the ability to receive push notifications on events happening on your workspace.

You can submit transfers via the API and receive real-time insights on transfers; sign all transaction types and messages securely with Raw Signing; set up automated transaction signing with Fireblocks' co-signer; manage your vault accounts, internal and external wallets, exchange accounts, fiat accounts, and network connections; and take advantage of the AML integration, among other features. All transfers are reflected in the Fireblocks Console, Transaction History, Audit Log, webhook, and API responses.

REST API

Getting Started

You can use our REST API to create transactions on the Fireblocks platform and view information regarding your vault accounts, FIAT accounts, connected wallets, exchanges, and network connections.

We offer SDKs in Python and JavaScript. You can view code examples to the right and switch between languages with the tabs in the top right. Additionally, you can view the API documentation with this online tool.

The API specification is also available in OpenAPI 3.0 (Swagger) format.

Issuing API Credentials

In order to add an API User to your Fireblocks workspace please contact Fireblocks Support to add an API user and indicate the permission level needed. Generate an API secret key for signing requests (see the Creating a Signed Request section for how to sign requests with the API secret key):
   * Run the following command line to generate an RSA 4096 private key (stored in fireblocks_secret.key):
     openssl req -new -newkey rsa:4096 -nodes -keyout fireblocks_secret.key -out fireblocks.csr
   * Make sure you keep the Fireblocks API secret key safe and secure!
   * Send the generated CSR file (fireblocks.csr) to Fireblocks Support.

Signing a Request

All API calls must be authenticated.
The base URL is: https://api.fireblocks.io

from fireblocks_sdk import FireblocksSDK, TransferPeerPath, DestinationTransferPeerPath, TRANSACTION_STATUS_CONFIRMED, TRANSACTION_STATUS_CANCELLED, TRANSACTION_STATUS_REJECTED, TRANSACTION_STATUS_FAILED, VAULT_ACCOUNT, TRANSACTION_MINT, TRANSACTION_BURN

apiSecret = open('fireblocks_secret.key', 'r').read()
apiKey = 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
fireblocks = FireblocksSDK(apiSecret, apiKey)
import fs from "fs";
import path from "path";
import {FireblocksSDK, PeerType, TransactionArguments, TransactionOperation, TransactionStatus} from "fireblocks-sdk";

apiSecret = fs.readFileSync(path.resolve(__dirname, "./fireblocks_secret.key"), "utf8");
const apiKey = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
fireblocks = new FireblocksSDK(apiSecret, apiKey);

Make sure to replace the apiKey with your API key.

Fireblocks uses API keys to authenticate all API calls. You can request an API key by contacting our support team.

Every request must contain the following headers:
X-API-Key - The API Key to be provided to you by Fireblocks.
Authorization - Its value should be set to Bearer <Access Token>, where the access token is a Base64-encoded JWT.

The JWT should be structured as follows:

Authorization: Bearer <JWT>

IP Whitelisting

Fireblocks supports restriction of API calls to be accepted only from a specific IP address per API key. If you wish to whitelist your IP address, please submit a ticket to Fireblocks Support with the IP of the machine running your API client and the matching API key.

API Idempotency

Fireblocks' API supports the submission of idempotent requests. Resubmission of the same request with the same idempotency key will not trigger the same operation again, but only return the original response. For example, this would be used to ensure a transaction request with the same idempotency key is not executed multiple times if you try to re-submit it due to network errors or delays experienced for a prior submission.
To make an idempotent request, please add Idempotency-Key: <key> header to your POST request. For any request with the Idempotency-Key header, we will store the response and re-send it for every request for the same idempotency key for 24H.

Rate Limiting

Fireblocks aims to provide a stable and secure platform for all users at all times. Accordingly, traffic is continuously monitored from all parties to identify patterns that may affect the network negatively.  Fireblocks only uses rate limits when traffic appears abnormal. If traffic from a single account is identified as too high, Fireblocks may temporarily throttle or restrict the account.
Error responses with status code 429 indicate that rate limits have been temporarily exceeded.
If normal operations repeatedly result in rate limiting, contact your account manager or Fireblocks support

Endpoints

Vault

List Vault Accounts


vault_accounts = fireblocks.get_vault_accounts()


const vaultAccounts = await fireblocks.getVaultAccounts();

The above command returns JSON structured like this:

[
  {
    "id": "string",
    "name": "string",
    "hiddenOnUI": false,
    "customerRefId": "string",
    "autoFuel": false,
    "assets": [
      {
        "id": "string",
        "total": "string",
        "available": "string",
        "pending": "string",
        "lockedAmount": "string",
        "totalStakedCPU": "string",
        "totalStakedNetwork": "string",
        "selfStakedCPU": "string",
        "selfStakedNetwork": "string",
        "pendingRefundCPU": "string",
        "pendingRefundNetwork": "string"
      }
    ]
  }
]

Retrieves all Vault Accounts in your workspace.

HTTP Request

GET /v1/vault/accounts

Query Parameters
Parameter Description
namePrefix Filter the response based on this account name prefix
nameSuffix Filter the response based on this account name prefix
minAmountThreshold Returns assets with total balance more than the provided threshold
assetId Returns only the wallets of the requested asset
Response

Returns an array of VaultAccount objects.

Retrieve a Vault Account


vault_account = fireblocks.get_vault_account(vault_account_id)


const vaultAccount = await fireblocks.getVaultAccount(vault_account_id);

The above command returns JSON structured like this:

{
  "id": "string",
  "name": "string",
  "hiddenOnUI": false,
  "customerRefId": "string",
  "autoFuel": false,
  "assets": [
    {
      "id": "string",
      "total": "string",
      "available": "string",
      "pending": "string",
      "lockedAmount": "string",
      "totalStakedCPU": "string",
      "totalStakedNetwork": "string",
      "selfStakedCPU": "string",
      "selfStakedNetwork": "string",
      "pendingRefundCPU": "string",
      "pendingRefundNetwork": "string"
    }
  ]
}

Returns the requested Vault Account.

HTTP Request

GET /v1/vault/accounts/{vaultAccountId}

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account beign retrieved
Response

Returns a VaultAccount object.

Create a New Vault Account


vaultAccount = fireblocks.create_vault_account(name, hiddenOnUI, customer_ref_id, auto_fueling)


const vaultAccount = await fireblocks.createVaultAccount(name, hiddenOnUI, customerRefId, autoFueling);

The above command returns JSON structured like this:

{
  "id": "string",
  "name": "string",
  "hiddenOnUI": false,
  "customerRefId": "string",
  "autoFuel": false,
  "assets": [
    {
      "id": "string",
      "total": "string",
      "available": "string",
      "pending": "string",
      "lockedAmount": "string",
      "staked": "string",
      "frozen": "string",
      "totalStakedCPU": "string",
      "totalStakedNetwork": "string",
      "selfStakedCPU": "string",
      "selfStakedNetwork": "string",
      "pendingRefundCPU": "string",
      "pendingRefundNetwork": "string",
      "blockHeight": "string",
      "blockHash": "string"
    }
  ]
}

Creates a new Vault Account with the requested name.

HTTP Request

POST /v1/vault/accounts

Body Parameters
Parameter Type Description
name string The name of the new account (this can be renamed later)
hiddenOnUI boolean [optional] Should be set to true if you wish this account will not appear in the web console, false by default
customerRefId string [optional] The ID for AML providers to associate the owner of funds with transactions
autoFuel boolean [optional] In case the Gas Station service is enabled on your workspace, this flag needs to be set to "true" if you wish to add this account's Ethereum address to be monitored and fueled upon detected deposits of ERC20 tokens.
Response

Returns a VaultAccount object.

Rename a Vault Account


vaultAccount = fireblocks.update_vault_account(vault_account_id, name)


const vaultAccount = await fireblocks.updateVaultAccount(vautlAccountId, name);

Make sure to replace vaultAccountId and name with the correct variables.

The above command returns JSON structured like this:

{
  "id": "string",
  "name": "string",
  "hiddenOnUI": false,
  "customerRefId": "string",
  "autoFuel": false,
  "assets": [
    {
      "id": "string",
      "total": "string",
      "available": "string",
      "pending": "string",
      "lockedAmount": "string",
      "staked": "string",
      "frozen": "string",
      "totalStakedCPU": "string",
      "totalStakedNetwork": "string",
      "selfStakedCPU": "string",
      "selfStakedNetwork": "string",
      "pendingRefundCPU": "string",
      "pendingRefundNetwork": "string",
      "blockHeight": "string",
      "blockHash": "string"
    }
  ]
}

Renames the requested vault account.

HTTP Request

PUT /v1/vault/accounts/{vaultAccountId}

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account to return, or 'default' for the default vault account
Body Parameters
Parameter Type Description
name string The new name of the vault account
Response

Returns 200 on success.

Retrieve the Balance of an Asset in a Vault Account


vaultAsset = fireblocks.get_vault_account_asset(vault_account_id, asset_id)


const vaultAsset = await fireblocks.getVaultAccountAsset(vaultAccountId, assetId);

The above command returns JSON structured like this:

{
  "id": "string",
  "total": "string",
  "available": "string",
  "pending": "string",
  "lockedAmount": "string",
  "staked": "string",
  "frozen": "string",
  "totalStakedCPU": "string",
  "totalStakedNetwork": "string",
  "selfStakedCPU": "string",
  "selfStakedNetwork": "string",
  "pendingRefundCPU": "string",
  "pendingRefundNetwork": "string",
  "blockHeight": "string",
  "blockHash": "string"
}

Retrieves a wallet of a specific asset under a Fireblocks Vault Account.

HTTP Request

GET /v1/vault/accounts/{vaultAccountId}/{assetId}

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account to return, or 'default' for the default vault account
assetId The ID of the asset
Response

Returns a VaultAsset object.

Create a New Wallet under the Vault Account


vaultAsset = fireblocks.create_vault_asset(vault_account_id, asset_id)


const vaultAsset = await fireblocks.createVaultAsset(vaultAccountId, assetId);

The above command returns JSON structured like this:

{
  "id": "string",
  "address": "string",
  "legacyAddress": "string",
  "tag": "string",
  "eosAccountName": "string"
}

Creates a new wallet of a specific asset under a Fireblocks Vault Account.

HTTP Request

POST /v1/vault/accounts/{vaultAccountId}/{assetId}

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account, or 'default' for the default vault account
assetId The ID of the asset
Body Parameters
Parameter Type Description
eosAccountName string [optional] EOS account address
Response

Returns CreateVaultAssetResponse.

Hide the Vault Account from the Web Console View


vaultAsset = fireblocks.hide_vault_account(vault_account_id)


const vaultAsset = await fireblocks.hideVaultAccount(vaultAccountId);

Hides the Vault Account from the web console view.

HTTP Request

POST /v1/vault/accounts/{vaultAccountId}/hide

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account to hide from the web console
Response

Returns 200 on success.

Return the Vault Account to be visible in the Web Console


vaultAsset = fireblocks.unhide_vault_account(vault_account_id)


const vaultAsset = await fireblocks.unhideVaultAccount(vaultAccountId);

Returns the Vault Account to be visible in the web console.

HTTP Request

POST /v1/vault/accounts/{vaultAccountId}/unhide

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account to be visible in the web console
Response

Returns 200 on success.

Retrieve the Addresses of an Asset in a Vault Account


depositAddresses = fireblocks.get_deposit_addresses(vault_account_id, asset_id)


const depositAddresses = await fireblocks.getDepositAddresses(vaultAccountId, assetId);

The above command returns JSON structured like this:

[
  {
    "assetId": "string",
    "address": "string",
    "legacyAddress": "string",
    "description": "string",
    "tag": "string",
    "type": "string",
    "bip44AddressIndex": 0
  }
]

Retrieves all addresses of a specific asset inside a Fireblocks Vault Account.

HTTP Request

GET /v1/vault/accounts/{vaultAccountId}/{assetId}/addresses

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account to return, or 'default' for the default vault account
assetId The ID of the asset
Body Parameters
Parameter Type Description
eosAccountName string [optional] EOS account address
Response

Returns an array of VaultAccountAssetAddress objects.

Create a New Deposit Address of an Asset in a Vault Account


address = fireblocks.generate_new_address(vault_account_id, asset_id, description, customer_ref_id)


const address = await fireblocks.generateNewAddress(vaultAccountId, assetId, description, customerRefId);

The above command returns JSON structured like this:

{
  "address": "string",
  "legacyAddress": "string",
  "tag": "string",
  "bip44AddressIndex": 0
}

Generates a new deposit address for the requested asset under the specific vault account.

HTTP Request

POST /v1/vault/accounts/{vaultAccountId}/{assetId}/addresses

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account, or 'default' for the default vault account
assetId The ID of the asset
Body Parameters
Parameter Description
description [optional] Description of the new address
customerRefId [optional] The ID for AML providers to associate the owner of funds with transactions
Response

Returns a CreateAddressResponse object.

Rename an Address


address = fireblocks.set_address_description(vault_account_id, asset_id, address, tag, description)


const address = await fireblocks.setAddressDescription(vaultAccountId, assetId, address, tag, description);

The above command returns JSON structured like this:

{
  "id": "string",
  "eosAccountName": "string"
}

Updates the description of an existing address of an asset within a Fireblocks Vault Account.

HTTP Request

PUT /v1/vault/accounts/{vaultAccountId}/{assetId}/addresses/{addressId}

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account, or 'default' for the default vault account
assetId The ID of the asset
addressId The address for which to add a description. For XRP/EOS/XLM, use :{tag or memo}, for all other assets, use only the address
Body Parameters
Parameter Type Description
description string [optional] Description of the new address
Response

Returns 200 on success.

Retrieve the Maximum Spendable Amount


address = fireblocks.get_max_spendable_amount(vault_account_id, asset_id)


const address = await fireblocks.getMaxSpendableAmount(vaultAccountId, assetId);

The above command returns JSON structured like this:

{
  "maxSpendableAmount": "string"
}

Retrieve the maximum amount that can be spent in a single transaction from this specific vault account. This endpoint is relevant only for UTXO assets. In UTXO based assets, each transaction is composed of multiple inputs and there is a limitation on the number of inputs you can embed in a single transaction, this call will allow you to retrieve the maximum amount in a single transaction from a specific vault account. In case you wish to spend more than the maximum spendable amount, please send several transactions.

HTTP Request

GET /v1/vault/accounts/{vaultAccountId}/{assetId}/max_spendable_amount

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account, or 'default' for the default vault account
assetId The ID of the asset
Query Parameters
Parameter Type Description
manualSigning boolean [optional] False by default. The maximum number of inputs depends if the transaction will be signed by an automated co-signer server or on a mobile device.
Response

Returns 200 on success.

Set an AML Customer Reference ID for Vault Account


vaultAsset = fireblocks.set_vault_account_customer_ref_id(vault_account_id, customer_ref_id)


const vaultAsset = await fireblocks.setCustomerRefIdForVaultAccount(vaultAccountId, customerRefId);

Sets an AML/KYT customer reference ID for the vault account

HTTP Request

POST /v1/vault/accounts/{vaultAccountId}/set_customer_ref_id

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account
Body Parameters
Parameter Type Description
customerRefId string The ID for AML providers to associate the owner of funds with transactions
Response

Returns 200 on success.

Set an AML Customer Reference ID for an Address


vaultAsset = fireblocks.set_customer_ref_id_for_address(vault_account_id, asset_id, address_id, customer_ref_id)


const vaultAsset = await fireblocks.setCustomerRefIdForAddress(vaultAccountId, assetId, addressId, customerRefId);

Sets an AML/KYT customer reference ID for the given address

HTTP Request

POST /v1/vault/accounts/{vaultAccountId}/{assetId}/addresses/{addressId}/set_customer_ref_id

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account
assetId The ID of the asset
addressId The address for which the customer reference ID should be added. For XRP/EOS/XLM, use :{tag or memo}, for all other assets, use only the address
Body Parameters
Parameter Type Description
customerRefId string The ID for AML providers to associate the owner of funds with transactions
Response

Returns 200 on success.

Retrieve Unspent Inputs


vaultAsset = fireblocks.get_unspent_inputs(vault_account_id, asset_id)


const vaultAsset = await fireblocks.getUnspentInputs(vaultAccountId, assetId);

Returns unspent inputs of the requested asset in the Vault Account.

HTTP Request

GET /v1/vault/accounts/{vaultAccountId}/{assetId}/unspent_inputs

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account
assetId The ID of the asset
Response

Returns UnspentInputsData object.

Retrieve Public Key by Derivation Path


pubKey = fireblocks.get_public_key_info(algorithm, derivation_path, compressed)


const PublicKeyInfoArgs = {
        algorithm: 'MPC_ECDSA_SECP256K1',
        derivationPath: '[44,0,0,0,0]'
}
const pubKey = await fireblocks.getPublicKeyInfo(PublicKeyInfoArgs);

Retrieves the public key of your Fireblocks' Vault.

HTTP Request

GET /v1/vault/public_key_info

Query Parameters
Parameter Description
algorithm String, one of the supported SigningAlgorithms
derivationPath List of integers.
compressed Boolean, whether the returned key should be in compressed format or not, false by default
Response

Returns PublicKey object.

Retrieve the Public Key of Fireblocks' Address


pubKey = fireblocks.get_public_key_info_for_vault_account(vault_account_id, asset_id, change, address_index, compressed)


const PublicKeyInfoForVaultAccountArgs = {
        assetId: 'assetId',
        vaultAccountId: 0,
        change: 0,
        addressIndex: 0
}
const pubKey = await fireblocks.getPublicKeyInfoForVaultAccount(PublicKeyInfoForVaultAccountArgs);

Retrieves the public key of your Fireblocks' Vault.

HTTP Request

GET /v1/vault/accounts/{vaultAccountId}/{assetId}/{change}/{addressIndex}/public_key_info

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account which address should be retrieved, or 'default' for the default vault account
assetId The ID of the asset
change Whether the address should be derived internal (change) or not
addressIndex The index of the address for the derivation path
Query Parameters
Parameter Description
compressed Boolean, whether the returned key should be in compressed format or not, false by default
Response

Returns PublicKey object.

Set Auto Fuel Properties of the Vault Account







This endpoint is relevant only if the Gas Station is enabled on your workspace!
Enable / Disable auto fueling of the Vault Account's Ethereum address

HTTP Request

POST /v1/vault/accounts/{vaultAccountId}/set_auto_fuel

URL Parameters
Parameter Description
vaultAccountId The ID of the vault account
Body Parameters
Parameter Type Description
autoFuel boolean Should be set to true if you wish to monitor this account's Ethereum address for incomming deposits.
Response

Returns 200 on success.

Retrieve Vault Balance by Assets


assets_balance = fireblocks.get_vault_assets_balance(accout_name_prefix, account_name_suffix)


const assetsBalance = await fireblocks.getVaultAssetsBalance(accountNamePrefix, accountNameSuffix);

The above command returns JSON structured like this:

[
  {
    "id": "string",
    "total": "string",
    "available": "string",
    "pending": "string",
    "frozen": "string",
    "lockedAmount": "string",
    "totalStakedCPU": "string",
    "totalStakedNetwork": "string",
    "selfStakedCPU": "string",
    "selfStakedNetwork": "string",
    "pendingRefundCPU": "string",
    "pendingRefundNetwork": "string"
  }
]

Returns the aggregated balance of your assets accross all Vault Accounts

HTTP Request

GET /v1/vault/assets

Query Parameters
Parameter Description
accountNamePrefix Filter the response based on this account name prefix
accountNameSuffix Filter the response based on this account name prefix
Response

Returns an array of VaultAsset objects.

Retrieve Asset's Vault Balance


assets_balance = fireblocks.get_vault_balance_by_asset(asset_id)


const assetsBalance = await fireblocks.getVaultBalanceByAsset(assetId);

The above command returns JSON structured like this:

{
  "id": "string",
  "total": "string",
  "available": "string",
  "pending": "string",
  "frozen": "string",
  "lockedAmount": "string",
  "totalStakedCPU": "string",
  "totalStakedNetwork": "string",
  "selfStakedCPU": "string",
  "selfStakedNetwork": "string",
  "pendingRefundCPU": "string",
  "pendingRefundNetwork": "string"
}

Returns the balance of the requested asset

HTTP Request

GET /v1/vault/assets/{assetId}

URL Parameters
Parameter Description
assetId The requested asset ID
Response

Returns a VaultAsset object.

Internal Wallets

Internal Wallets are your whitelisted addresses outside of Fireblocks. You can see each wallet's balances and transfer funds here.

List Internal Wallets


internalWallets = fireblocks.get_internal_wallets()


const internalWallets = await fireblocks.getInternalWallets();

The above command returns JSON structured like this:

[
  {
    "id": "string",
    "name": "string",
    "customerRefId": "string",
    "assets": [
      {
        "id": "string",
        "balance": "string",
        "lockedAmount": "string",
        "status": "WAITING_FOR_APPROVAL",
        "activationTime":"string",
        "address": "string",
        "tag": "string"
      }
    ]
  }
]

Retrieves all Internal Wallets in your workspace.

HTTP Request

GET /v1/internal_wallets

Response

Returns an array of UnmanagedWallet objects.

Create a New Internal Wallet


internalWallet = fireblocks.create_internal_wallet(name, customer_ref_id)


const internalWallet = await fireblocks.createInternalWallet(name, customerRefId);

The above command returns JSON structured like this:

{
  "id": "string",
  "name": "string",
  "customerRefId": "string",
  "assets": [
    {
      "id": "string",
      "balance": "string",
      "lockedAmount": "string",
      "status": "WAITING_FOR_APPROVAL",
      "activationTime":"string",
      "address": "string",
      "tag": "string"
    }
  ]
}

Creates a new Internal Wallet container.

HTTP Request

POST /v1/internal_wallets

Body Parameters
Parameter Type Description
name string The wallet container's display name
customerRefId string [optional] The ID for AML providers to associate the owner of funds with transactions
Response

Returns an UnmanagedWallet objects.

Retrieve an Internal Wallet


internalWallet = fireblocks.get_internal_wallet(walletId)


const result = await fireblocks.getInternalWallet(walletId);

The above command returns JSON structured like this:

{
  "id": "string",
  "name": "string",
  "customerRefId": "string",
  "assets": [
    {
      "id": "string",
      "balance": "string",
      "lockedAmount": "string",
      "status": "WAITING_FOR_APPROVAL",
      "activationTime":"string",
      "address": "string",
      "tag": "string"
    }
  ]
}

Retrieves all assets under the Internal Wallet.

HTTP Request

GET /v1/internal_wallets/{walletId}

URL Parameters
Parameter Description
walletId The ID of the wallet to return
Response

Returns an array of UnmanagedWallet objects.

Delete an Internal Wallet


result = firebocks.delete_internal_wallet(walletId)


const result = await fireblocks.deleteInternalWallet(walletId);

The above command returns 200 (OK)

Deletes an Internal Wallet container.

HTTP Request

DELETE /v1/internal_wallets/{walletId}

URL Parameters
Parameter Description
walletId The ID of the wallet to delete
Response

Returns 200 on success.

Retrieve an Asset from an Internal Wallet


internalWalletAsset = fireblocks.get_internal_wallet_asset(walletId, assetId)


const internalWalletAsset = fireblocks.getInternalWalletAsset(walletId, assetId);

The above command returns JSON structured like this:

{
  "id": "string",
  "balance": "string",
  "lockedAmount": "string",
  "status": "WAITING_FOR_APPROVAL",
  "activationTime":"string",
  "address": "string",
  "tag": "string"
}

Retrieves the information on a specific asset within an Internal Wallet.

HTTP Request

GET /v1/internal_wallets/{walletId}/{assetId}

URL Parameters
Parameter Description
walletId The ID of the wallet to return
assetId The ID of the asset to return
Response

Returns WalletAsset object.

Add an Asset to an Internal Wallet


internalWalletAsset = fireblocks.create_internal_wallet_asset(walletId, assetId, address, tag)


const internalWalletAsset = await fireblocks.createInternalWalletAsset(walletContainerId, assetId, address, tag);

The above command returns JSON structured like this:

{
  "id": "string",
  "balance": "string",
  "lockedAmount": "string",
  "status": "WAITING_FOR_APPROVAL",
  "activationTime":"string",
  "address": "string",
  "tag": "string"
}

Adds an address to an existing Internal Wallet container.

HTTP Request

POST /v1/internal_wallets/{walletId}/{assetId}

URL Parameters
Parameter Description
walletId The ID of the wallet to return
assetId The ID of the asset to return
Body Parameters
Parameter Type Description
address string The wallet's address or, for EOS wallets, the account name
tag string For XRP wallets, the destination tag; for EOS/XLM, the memo; for Signet/SEN, the Bank Transfer Description
Response

Returns WalletAsset object.

Delete an Asset from an Internal Wallet


result = fireblocks.delete_internal_wallet_asset(walletId, assetId)


const result = await fireblocks.deleteInternalWalletAsset(walletId, assetId);

The above command returns 200 (OK)

Deletes an asset from an Internal Wallet.

HTTP Request

DELETE /v1/internal_wallets/{walletId}/{assetId}

URL Parameters
Parameter Description
walletId The ID of the wallet to delete
assetId The ID of the asset to delete
Response

Returns 200 success.

Set an AML Customer Reference ID for an Internal Wallet


result = firebocks.set_customer_ref_id_for_internal_wallet(wallet_id, customer_ref_id)


const result = await fireblocks.setCustomerRefIdForInternalWallet(walletId, customerRefId);

The above command returns 200 (OK)

Sets an AML/KYT customer reference ID for the specific internal wallet

HTTP Request

POST /v1/internal_wallets/{walletId}/set_customer_ref_id

URL Parameters
Parameter Description
walletId The ID of the wallet to be added with the customer reference ID
Body Parameters
Parameter Type Description
customerRefId string The ID for AML providers to associate the owner of funds with transactions
Response

Returns 200 success.

External Wallets

External Wallets are your counterparties’ wallets. These are addresses you wish to whitelist as transfer destinations.

List External Wallets


externalWallets = fireblocks.get_external_wallets()


const externalWallets = await fireblocks.getExternalWallets();

The above command returns JSON structured like this:

[
  {
    "id": "string",
    "name": "string",
    "customerRefId": "string",
    "assets": [
      {
        "id": "string",
        "status": "WAITING_FOR_APPROVAL",
        "activationTime":"string",
        "address": "string",
        "tag": "string"
      }
    ]
  }
]

Retrieves all External Wallets in your workspace.

HTTP Request

GET /v1/external_wallets

Response

Returns an array of ExternalWallet objects.

Create a New External Wallet


externalWallet = fireblocks.create_external_wallet(name, customer_ref_id)


const externalWallet = await fireblocks.createExternalWallet(name, customerRefId);

The above command returns JSON structured like this:

{
  "id": "string",
  "name": "string",
  "customerRefId": "string",
  "assets": [
    {
      "id": "string",
      "status": "WAITING_FOR_APPROVAL",
      "activationTime":"string",
      "address": "string",
      "tag": "string"
    }
  ]
}

Creates a new External Wallet.

HTTP Request

POST /v1/external_wallets

Body Parameters
Parameter Type Description
name string The wallet's display name
customerRefId string [optional] The ID for AML providers to associate the owner of funds with transactions
Response

Returns an ExternalWallet object.

Retrieve an External Wallet


externalWallet = fireblocks.get_external_wallet(walletId)


const externalWallet = await fireblocks.getExternalWallet(walletId);

The above command returns JSON structured like this:

{
  "id": "string",
  "name": "string",
  "customerRefId": "string",
  "assets": [
    {
      "id": "string",
      "status": "WAITING_FOR_APPROVAL",
      "activationTime":"string",
      "address": "string",
      "tag": "string"
    }
  ]
}

Retrieves the External Wallet for the request wallet ID.

HTTP Request

GET /v1/external_wallets/{walletId}

URL Parameters
Parameter Description
walletId The ID of the wallet to return
Response

Returns an ExternalWallet object.

Delete an External Wallet


result = firebocks.delete_external_wallet(walletId)


const result = await fireblocks.deleteExternalWallet(walletId);

The above command returns 200 (OK)

Deletes an External Wallet.

HTTP Request

DELETE /v1/external_wallets/{walletId}

URL Parameters
Parameter Description
walletId The ID of the wallet to delete
Response

Returns 200 on success.

Retrieve an Asset from an External Wallet


externalWalletAsset = fireblocks.get_external_wallet_asset(walletId, assetId)


const externalWalletAsset = fireblocks.getExternalWalletAsset(walletId, assetId)

The above command returns JSON structured like this:

{
  "id": "string",
  "status": "WAITING_FOR_APPROVAL",
  "activationTime":"string",
  "address": "string",
  "tag": "string"
}

Retrieves the External Wallet of the requested wallet ID and asset.

HTTP Request

GET /v1/external_wallets/{walletId}/{assetId}

URL Parameters
Parameter Description
walletId The ID of the wallet to return
assetId The ID of the asset to return
Response

Returns an ExternalWalletAsset object.

Add an Asset to an External Wallet


externalWalletAsset = fireblocks.create_external_wallet_asset(walletId, assetId, address, tag)


const externalWalletAsset = await fireblocks.createExternalWalletAsset(walletContainerId, assetId, address, tag);

The above command returns JSON structured like this:

{
  "id": "string",
  "status": "WAITING_FOR_APPROVAL",
  "activationTime":"string",
  "address": "string",
  "tag": "string"
}

Adds an address to an existing External Wallet.

HTTP Request

POST /v1/external_wallets/{walletId}/{assetId}

URL Parameters
Parameter Description
walletId The ID of the wallet to return
assetId The ID of the asset to return
Body Parameters
Parameter Type Description
address string The wallet's address or, for EOS wallets, the account name
tag string For XRP wallets, the destination tag; for EOS/XLM, the memo; for Signet/SEN, the Bank Transfer Description
Response

Returns an ExternalWalletAsset object.

Delete an Asset from an External Wallet


result = fireblocks.delete_external_wallet_asset(walletId, assetId)


const result = await fireblocks.deleteExternalWalletAsset(walletId, assetId);

The above command returns 200 (OK)

Deletes an external wallet asset.

HTTP Request

DELETE /v1/external_wallets/{walletId}/{assetId}

URL Parameters
Parameter Description
walletId The ID of the wallet to delete
assetId The ID of the asset to delete
Response

Returns 200 on success.

Set an AML Customer Reference ID for an External Wallet


result = firebocks.set_customer_ref_id_for_external_wallet(wallet_id, customer_ref_id)


const result = await fireblocks.setCustomerRefIdForExternalWallet(walletId, customerRefId);

The above command returns 200 (OK)

Sets an AML/KYT customer reference ID for the specific external wallet

HTTP Request

POST /v1/external_wallets/{walletId}/set_customer_ref_id

URL Parameters
Parameter Description
walletId The ID of the wallet to be added with the customer reference ID
Body Parameters
Parameter Type Description
customerRefId string The ID for AML providers to associate the owner of funds with transactions
Response

Returns 200 on success.

Exchange Accounts

View your exchange accounts connected to your Fireblocks workspace.

List Exchange Accounts


exchangeAccounts = fireblocks.get_exchange_accounts()


const exchangeAccounts = await fireblocks.getExchangeAccounts();

The above command returns JSON structured like this:

[
  {
    "id": "string",
    "type": "BITTREX",
    "name": "string",
    "status": "string",
    "assets": [
      {
        "id": "string",
        "total": "string",
        "available": "string",
        "lockedAmount": "string"
      }
    ],
    "tradingAccounts": [
      {
        "type": "SPOT",
        "assets": [
          {
            "id": "string",
            "total": "string",
            "available": "string",
            "lockedAmount": "string"
          }
        ]
      }
    ],
    "isSubaccount": true,
    "mainAccountId": "string",
    "fundableAccountType": "SPOT"
  }
]

Fetches all the exchange accounts.

HTTP Request

GET /v1/exchange_accounts

Response

Returns an array of ExchangeAccount objects.

Retrieve a Specific Exchange Account


exchangeAccount = fireblocks.get_exchange_account(exchangeAccountId)


const exchnageAccount = await fireblocks.get_exchange_account(exchangeAccountId);

The above command returns JSON structured like this:

{
  "id": "string",
  "type": "BITTREX",
  "name": "string",
  "status": "string",
  "assets": [
    {
      "id": "string",
      "total": "string",
      "available": "string",
      "lockedAmount": "string"
    }
  ],
  "tradingAccounts": [
    {
      "type": "SPOT",
      "assets": [
        {
          "id": "string",
          "total": "string",
          "available": "string",
          "lockedAmount": "string"
        }
      ]
    }
  ],
  "isSubaccount": true,
  "mainAccountId": "string",
  "fundableAccountType": "SPOT"
}

Retrieves the Exchange Account associated with the requested exchange account ID.

HTTP Request

GET /v1/exchange_accounts/{exchangeAccountId}

URL Parameters
Parameter Description
exchangeAccountId The ID of the exchange account to return
Response

Returns an ExchangeAccount object.

Retrieve a Specific Asset Within an Exchange Account


exchangeAsset = fireblocks.get_exchange_asset(exchangeAccountId, assetId)


const exchangeAsset = await fireblocks.getExchangeAsset(exchangeAccountId, assetId);

The above command returns JSON structured like this:

{
  "id": "string",
  "total": "string",
  "available": "string",
  "lockedAmount": "string"
}

Retrieves a single asset within an Exchange Account.

HTTP Request

GET /v1/exchange_accounts/{exchangeAccountId}/{assetId}

URL Parameters
Parameter Description
exchangeAccountId The ID of the exchange account to return
assetId The ID of the asset to return
Response

Returns an ExchangeAsset object.

Exchange's Internal Transfer







The above command returns 200 (OK)

Transfers funds between trading accounts under the same exchange account.

HTTP Request

POST /v1/exchange_accounts/{exchangeAccountId}/internal_transfer

URL Parameters
Parameter Description
exchangeAccountId The ID of the exchange account
Body Parameters
Parameter Type Description
sourceType TradingAccountType The type of the source trading account
destType TradingAccountType The type of the source trading account
asset string The asset you wish to transfer
amount string The amount to transfer
Response

Returns 200 on success.

Fiat Accounts

View and operate with your linked Fiat accounts

List Fiat Accounts


transactions = fireblocks.get_fiat_accounts()


const transactions = await fireblocks.getFiatAccounts();

The above command returns JSON structured like this:

[
  {
    "id": "string",
    "type": "SIGNET",
    "name": "string",
    "address": "string",
    "assets": [
      {
        "id": "string",
        "balance": "string"
      }
    ]
  }
]

Retrieves all the FIAT accounts linked to your workspace.

HTTP Request

GET /v1/fiat_accounts

Response

Returns an array of FiatAccount object.

Retrieve a Specific Fiat Accounts


transactions = fireblocks.get_fiat_account_by_id(account_id)


const transactions = await fireblocks.getFiatAccountById(accountId);

The above command returns JSON structured like this:

{
  "id": "string",
  "type": "SIGNET",
  "name": "string",
  "address": "string",
  "assets": [
    {
      "id": "string",
      "balance": "string"
    }
  ]
}

Retrieve the requested FIAT account.

HTTP Request

GET /v1/fiat_accounts/{accountId}

URL Parameters
Parameter Description
accountId The ID of the fiat account
Response

Returns a FiatAccount object.

Redeem Funds to Linked DDA


transactions = fireblocks.redeem_to_linked_dda(account_id, amount)


const transactions = await fireblocks.redeemToLinkedDDA(accountId, amount);

The above command returns 200 (OK)

Redeem funds to the connected DDA.

HTTP Request

POST /v1/fiat_accounts/{accountId}/redeem_to_linked_dda

URL Parameters
Parameter Description
accountId The ID of the fiat account
Body Parameters
Parameter Type Description
amount string The reqested amount
Response

Returns 200 on success.

Deposit Funds from Linked DDA


transactions = fireblocks.deposit_from_linked_dda(account_id, amount)


const transactions = await fireblocks.depositFromLinkedDDA(accountId, amount);

The above command returns 200 (OK)

Deposit funds from the connected DDA.

HTTP Request

POST /v1/fiat_accounts/{accountId}/deposit_from_linked_dda

URL Parameters
Parameter Description
accountId The ID of the fiat account
Body Parameters
Parameter Type Description
amount string The reqested amount
Response

Returns 200 on success.

Transactions

Transfer management endpoints.

List Transactions


transactions = fireblocks.get_transactions()

const transactions = await fireblocks.getTransactions({
        status: args.status,
        after: from
        });

The above command returns JSON structured like this:

[
  {
    "id": "string",
    "assetId": "string",
    "source": {
      "type": "VAULT_ACCOUNT",
      "id": "string",
      "name": "string",
      "subType": "string"
    },
    "destination": {
      "type": "VAULT_ACCOUNT",
      "id": "string",
      "name": "string",
      "subType": "string"
    },
    "amountInfo": {
      "amount": "string",
      "requestedAmount": "string",
      "netAmount": "string",
      "amountUSD": "string"
    },
    "treatAsGrossAmount": false,
    "feeInfo": {
      "networkFee": "string",
      "serviceFee": "string"
    },
    "requestedAmount": 0,
    "amount": 0,
    "netAmount": 0,
    "amountUSD": 0,
    "serviceFee": 0,
    "networkFee": 0,
    "createdAt": 213456789,
    "lastUpdated": 213456789,
    "status": "SUBMITTED",
    "txHash": "string",
    "index": 0,
    "tag": "string",
    "subStatus": "INSUFFICIENT_FUNDS",
    "sourceAddress": "string",
    "destinationAddress": "string",
    "destinationAddressDescription": "string",
    "destinationTag": "string",
    "signedBy": [
      "string"
    ],
    "createdBy": "string",
    "rejectedBy": "string",
    "addressType": "string",
    "note": "string",
    "exchangeTxId": "string",
    "feeCurrency": "string",
    "operation": "TRANSFER",
    "networkRecords": [
      {
        "source": {
          "type": "VAULT_ACCOUNT",
          "id": "string",
          "name": "string",
          "subType": "string"
        },
        "destination": {
          "type": "VAULT_ACCOUNT",
          "id": "string",
          "name": "string",
          "subType": "string"
        },
        "txHash": "string",
        "networkFee": "string",
        "assetId": "string",
        "netAmount": "string",
        "status": "DROPPED",
        "type": "string",
        "destinationAddress": "string",
        "sourceAddress": "string"
      }
    ],
    "amlScreeningResult": {
      "provider": "string",
      "payload": {}
    },
    "customerRefId": "string",
    "numOfConfirmations": 0,
    "signedMessages": [
      {
        "content": "string",
        "algorithm": "ECDSA",
        "derivationPath": [
          1,1,0,10
        ],
        "signature": {
          "r": "string",
          "s": "string",
          "v": 0
        },
        "publicKey": "string"
      }
    ],
    "replacedTxHash": "string",
    "externalTxId": "string",
    "authorizationInfo": {
      "allowOperatorAsAuthorizer": true,
      "logic": "AND",
      "groups": [
        {
          "th": 0,
          "users": {
            "usedId1": "PENDING_AUTHORIZATION",
            "usedId2": "PENDING_AUTHORIZATION",
            "usedId3": "PENDING_AUTHORIZATION"
          }
        }
      ]
    },
    "extraParameters": { }
  }
]

Lists the transaction history for your workspace.

HTTP Request

GET /v1/transactions

Query Parameters
Parameter Description
before [optional] Unix timestamp in milliseconds. Returns only transactions created before the specified date
after [optional] Unix timestamp in milliseconds. Returns only transactions created after the specified date
status [optional] Comma-separated list of statuses. Returns only transactions with each of the specified statuses
orderBy [optional] The field to order the results by. Available values : createdAt (default), lastUpdated
sourceType [optional] The source type of the transaction. Available values: VAULT_ACCOUNT, EXCHANGE_ACCOUNT, INTERNAL_WALLET, EXTERNAL_WALLET, FIAT_ACCOUNT, NETWORK_CONNECTION, COMPOUND
sourceId [optional] The source ID of the transaction
destType [optional] The destination type of the transaction. Available values: VAULT_ACCOUNT, EXCHANGE_ACCOUNT, INTERNAL_WALLET, EXTERNAL_WALLET, ONE_TIME_ADDRESS, FIAT_ACCOUNT, NETWORK_CONNECTION, COMPOUND
destId [optional] The destination ID of the transaction
assets [optional] A list of assets to filter by, seperated by commas
txHash [optional] Returns only results with a specified txHash
limit [optional] Limits the number of returned transactions. If not provided, a defult of 200 will be returned. The maximum allowed limit is 500.
Response

Returns an array of TransactionDetails object.
The response is paginated with a default of 200 results per page. The response will have two headers, next-page and prev-page which are the URLs you need to query to receive the next or previous page respectfully.

Create a New Transaction


tx_result = client.create_transaction(
        asset_id="BTC",
        amount="50",
        source=TransferPeerPath(VAULT_ACCOUNT, from_vault_account_id),
        destination=DestinationTransferPeerPath(VAULT_ACCOUNT, to_vault_account_id)
        )

const payload: TransactionArguments = {
    assetId: asset,
    source: {
        type: sourceType,
        id: sourceId || 0
    },
    destination: {
        type: destinationType,
        id: String(destinationId)
    },
    amount: String(amount),
    fee: String(fee),
    note: "Created by fireblocks SDK"
};

const result = await fireblocks.createTransaction(payload);

The above command returns JSON structured like this:

{
  "id": "string",
  "status": "string"
}

Submits a new transaction on the Fireblocks platform.

HTTP Request

POST /v1/transactions

Body Parameters
Parameter Type Description
assetId string The ID of the asset
source TransferPeerPath The source account of the transaction
destination DestinationTransferPeerPath The destination of the transaction
destinations array of TransactionRequestDestination For UTXO based assets, you can send a single transaction to multiple destinations which should be specified using this field
amount string The requested amount to transfer
treatAsGrossAmount boolean False by default, if set to true the network fee will be deducted from the requested amount
fee string [optional] For UTXO assets, the fee per bytes in the asset's smallest unit (Satoshi, Latoshi, etc.)
For XRP, the fee for the transaction
gasPrice string [optional] For ETH-based assets only this will be used instead of the fee property, value is in Gwei
gasLimit string [optional] For ETH-based assets only
networkFee string [optional] The transaction blockchain fee (For Ethereum, you can't pass gasPrice, gasLimit and networkFee all together)
priorityFee string [optional] The priority fee of Ethereum transaction according to EIP-1559
feeLevel string [optional] LOW / MEDIUM / HIGH - Defines the blockchain fee level which will be payed for the transaction. Only for Ethereum and UTXO blockchains.
maxFee string [optional] The maximum fee (gas price or fee per byte) that should be payed for the transaction. In case the current value of the requested fee level is higher than this requested maximum fee.
failOnLowFee boolean [optional] False by default, if set to true and the current MEDIUM fee level is higher than the one specified in the transaction, the transction will fail to avoid getting stuck with 0 confirmations.
forceSweep boolean For "DOT" transactions only, "false" by default, if set to "true" Fireblocks will allow emptying the DOT wallet.
note string [optional] Note to be added to the transaction history
autoStaking boolean [optional] Deprecated
networkStaking string [optional] Deprecated
cpuStaking string [optional] Deprecated
operation TransactionOperation [optional] Transaction operation type, the default is "TRANSFER"
customerRefId string [optional] The ID for AML providers to associate the owner of funds with transactions
replaceTxByHash string [optional] For Ethereum blockchain transactions, the hash of the stuck transaction to be replaced (RBF)
externalTxId string [optional] Unique transaction ID provided by the user. Future transactions with same ID will be rejected
extraParameters JSON object [optional] Use for protocol / operation specific parameters.
For raw signing, pass rawMessageData field.
For contract calls, pass contractCallData (See here for more details on Smart Contract API and contract calls).
For UTXO based blockchains inputs selectios pass inputsSelection following this structure. The inputs can be retrieved from Retrieve Unspent Inputs
Response

Returns a CreateTransactionResponse object. The response is paginated, the default response sise is up to 200 entries.

Retrieve a Specific Transaction


tx = fireblocks.get_transaction_by_id(txId)


  const tx = await fireblocks.getTransactionById(txId);

The above command returns JSON structured like this:

{
  "id": "string",
  "assetId": "string",
  "source": {
    "type": "VAULT_ACCOUNT",
    "id": "string",
    "name": "string",
    "subType": "string"
  },
  "destination": {
    "type": "VAULT_ACCOUNT",
    "id": "string",
    "name": "string",
    "subType": "string"
  },
  "amountInfo": {
    "amount": "string",
    "requestedAmount": "string",
    "netAmount": "string",
    "amountUSD": "string"
  },
  "treatAsGrossAmount": false,
  "feeInfo": {
    "networkFee": "string",
    "serviceFee": "string"
  },
  "requestedAmount": 0,
  "amount": 0,
  "netAmount": 0,
  "amountUSD": 0,
  "serviceFee": 0,
  "networkFee": 0,
  "createdAt": 123456789,
  "lastUpdated": 123456789,
  "status": "SUBMITTED",
  "txHash": "string",
  "index": 0,
  "tag": "string",
  "subStatus": "INSUFFICIENT_FUNDS",
  "sourceAddress": "string",
  "destinationAddress": "string",
  "destinationAddressDescription": "string",
  "destinationTag": "string",
  "signedBy": [
    "string"
  ],
  "createdBy": "string",
  "rejectedBy": "string",
  "addressType": "string",
  "note": "string",
  "exchangeTxId": "string",
  "feeCurrency": "string",
  "operation": "TRANSFER",
  "networkRecords": [
    {
      "source": {
        "type": "VAULT_ACCOUNT",
        "id": "string",
        "name": "string",
        "subType": "string"
      },
      "destination": {
        "type": "VAULT_ACCOUNT",
        "id": "string",
        "name": "string",
        "subType": "string"
      },
      "txHash": "string",
      "networkFee": "string",
      "assetId": "string",
      "netAmount": "string",
      "status": "DROPPED",
      "type": "string",
      "destinationAddress": "string",
      "sourceAddress": "string"
    }
  ],
  "amlScreeningResult": {
    "provider": "string",
    "payload": {}
  },
  "customerRefId": "string",
  "numOfConfirmations": 0,
  "signedMessages": [
    {
      "content": "string",
      "algorithm": "ECDSA",
      "derivationPath": [
        1,1,0,10
      ],
      "signature": {
          "r": "string",
          "s": "string",
          "v": 0
      },
      "publicKey": "string"
    }
  ],
  "replacedTxHash": "string",
  "externalTxId": "string",
  "blockInfo": {
    "blockHeight": "string",
    "blockHash": "string"
  },
  "authorizationInfo": {
    "allowOperatorAsAuthorizer": true,
    "logic": "AND",
    "groups": [
      {
        "th": 0,
        "users": {
          "usedId1": "PENDING_AUTHORIZATION",
          "usedId2": "PENDING_AUTHORIZATION",
          "usedId3": "PENDING_AUTHORIZATION"
        }
      }
    ]
  },
  "extraParameters": { }
}

Retrieves a specific transaction for the requested transaction ID.

HTTP Request

GET /v1/transactions/{txId}

URL Parameters
Parameter Description
txId The ID of the transaction to return
Response

Returns a TransactionDetails object.

Retrieve a Specific Transaction By External ID


tx = fireblocks.get_transaction_by_external_tx_id(externalTxId)


  const tx = await fireblocks.getTransactionByExternalTxId(externalTxId);

The above command returns JSON structured like this:

{
  "id": "string",
  "assetId": "string",
  "source": {
    "type": "VAULT_ACCOUNT",
    "id": "string",
    "name": "string",
    "subType": "string"
  },
  "destination": {
    "type": "VAULT_ACCOUNT",
    "id": "string",
    "name": "string",
    "subType": "string"
  },
  "amountInfo": {
    "amount": "string",
    "requestedAmount": "string",
    "netAmount": "string",
    "amountUSD": "string"
  },
  "feeInfo": {
    "networkFee": "string",
    "serviceFee": "string"
  },
  "requestedAmount": 0,
  "amount": 0,
  "netAmount": 0,
  "amountUSD": 0,
  "serviceFee": 0,
  "networkFee": 0,
  "createdAt": 123456789,
  "lastUpdated": 123456789,
  "status": "SUBMITTED",
  "txHash": "string",
  "index": 0,
  "tag": "string",
  "subStatus": "INSUFFICIENT_FUNDS",
  "sourceAddress": "string",
  "destinationAddress": "string",
  "destinationAddressDescription": "string",
  "destinationTag": "string",
  "signedBy": [
    "string"
  ],
  "createdBy": "string",
  "rejectedBy": "string",
  "addressType": "string",
  "note": "string",
  "exchangeTxId": "string",
  "feeCurrency": "string",
  "operation": "TRANSFER",
  "networkRecords": [
    {
      "source": {
        "type": "VAULT_ACCOUNT",
        "id": "string",
        "name": "string",
        "subType": "string"
      },
      "destination": {
        "type": "VAULT_ACCOUNT",
        "id": "string",
        "name": "string",
        "subType": "string"
      },
      "txHash": "string",
      "networkFee": "string",
      "assetId": "string",
      "netAmount": "string",
      "status": "DROPPED",
      "type": "string",
      "destinationAddress": "string",
      "sourceAddress": "string"
    }
  ],
  "amlScreeningResult": {
    "provider": "string",
    "payload": {}
  },
  "customerRefId": "string",
  "numOfConfirmations": 0,
  "signedMessages": [
    {
      "content": "string",
      "algorithm": "ECDSA",
      "derivationPath": [
        1,1,0,10
      ],
      "signature": {
          "r": "string",
          "s": "string",
          "v": 0
      },
      "publicKey": "string"
    }
  ],
  "replacedTxHash": "string",
  "externalTxId": "string",
  "blockInfo": {
    "blockHeight": "string",
    "blockHash": "string"
  },
  "authorizationInfo": {
    "allowOperatorAsAuthorizer": true,
    "logic": "AND",
    "groups": [
      {
        "th": 0,
        "users": {
          "usedId1": "PENDING_AUTHORIZATION",
          "usedId2": "PENDING_AUTHORIZATION",
          "usedId3": "PENDING_AUTHORIZATION"
        }
      }
    ]
  },
  "extraParameters": { }
}

Retrieves a specific transaction for the requested external transaction ID.

HTTP Request

GET /v1/transactions/external_tx_id/{externalTxId}

URL Parameters
Parameter Description
externalTxId The external ID of the transaction provided by the user
Response

Returns a TransactionDetails object.

Cancel Transaction


result = fireblocks.cancel_transaction_by_id(txId)


const result = await fireblocks.cancelTransactionById(txId);

The above command returns JSON structured like this:

{
  "success": true
}

Cancel the requested transaction.

HTTP Request

POST /v1/transactions/{txId}/cancel

URL Parameters
Parameter Description
txId The ID of the transaction to return
Response

Returns the status of the request.

Drop Transaction


result = fireblocks.drop_transaction(txId, fee_level)


const result = await fireblocks.dropTransaction(txId, feeLevel);

The above command returns JSON structured like this:

{
  "success": true
}

Replaces Ethereum transactions that are stuck with 0 confirmation. This request creates a new transaction that can replace the stalled transaction, with the same source as the original one, with 0 ETH sent to itself. By using the same nonce as the original one, it will drop the original transaction once the new transaction will be mined.
A stuck transaction can be replaced by a different transaction using the create transaction endpoint and the "replaceTxByHash" field.

HTTP Request

POST /v1/transactions/{txId}/drop

URL Parameters
Parameter Description
txId The ID of the transaction to return
Body Parameters
Parameter Type Description
feeLevel string [optional] The requested fee level of the dropping transaction (LOW / MEDIUM / HIGH)
Response

Returns the transaction id of the replacing transaction.

Freeze Transaction


result = fireblocks.freeze_transaction(txId)


const result = await fireblocks.freezeTransaction(txId);

The above command returns JSON structured like this:

{
  "success": true
}

Freezes transaction so that it will not be available for spending

HTTP Request

POST /v1/transactions/{txId}/freeze

URL Parameters
Parameter Description
txId The ID of the transaction to return
Response

Returns the status of the request

Unfreeze Transaction


result = fireblocks.unfreeze_transaction(txId)


const result = await fireblocks.unfreezeTransaction(txId);

The above command returns JSON structured like this:

{
  "success": true
}

Makes the transaction avaialble after it was frozen.

HTTP Request

POST /v1/transactions/{txId}/unfreeze

URL Parameters
Parameter Description
txId The ID of the transaction to return
Response

Returns the status of the request.

Validate Destination Address


result = fireblocks.(asset_id, address)


const result = await fireblocks.(assetId, address);

The above command returns JSON structured like this:

{
  "isValid": true,
  "isActive": true,
  "requiresTag": true
}

This endpoint validates the destination address exists or is activate with the necessary activation per blockchain. Supported for the following assets: XRP, DOT, XLM, EOS.

HTTP Request

GET /v1/transactions/validate_address/{assetId}/{address}

URL Parameters
Parameter Description
assetId The asset of the address
address The address to validate
Response

Returns the AddressStatus object.

Retrieve Network Fee


fee_result = fireblocks.get_fee_for_asset(asset_id)


const feeResult = await fireblocks.getFeeForAsset(assetId);

The above command returns JSON structured like this:

{
  "low": {
    "feePerByte": "string",
    "gasPrice": "string",
    "networkFee": "string"
  },
  "medium": {
    "feePerByte": "string",
    "gasPrice": "string",
    "networkFee": "string"
  },
  "high": {
    "feePerByte": "string",
    "gasPrice": "string",
    "networkFee": "string"
  }
}

Retrieves the current blockchain fees based on the requested asset.

HTTP Request

GET /v1/estimate_network_fee

Query Parameters
Parameter Description
assetId The asset for which you wish to retrieve the network fees
Response

Returns NetworkFee objects for low, medium and high fees.

Estimate Transaction Fee


estimated_fee = client.estimate_fee_for_transaction(
        asset_id="BTC",
        amount="50",
        source=TransferPeerPath(VAULT_ACCOUNT, from_vault_account_id),
        destination=DestinationTransferPeerPath(VAULT_ACCOUNT, to_vault_account_id)
        )

const payload: TransactionArguments = {
    assetId: asset,
    source: {
        type: sourceType,
        id: sourceId || 0
    },
    destination: {
        type: destinationType,
        id: String(destinationId)
    },
    amount: Number(amount)
};

const estimatedFee = await fireblocks.estimateFeeForTransaction(payload);

The above command returns JSON structured like this:

{
  "low": {
    "feePerByte": "string",
    "gasPrice": "string",
    "gasLimit": "string",
    "networkFee": "string"
  },
  "medium": {
    "feePerByte": "string",
    "gasPrice": "string",
    "gasLimit": "string",
    "networkFee": "string"
  },
  "high": {
    "feePerByte": "string",
    "gasPrice": "string",
    "gasLimit": "string",
    "networkFee": "string"
  }
}

Estimates the transaction fee for a given transaction request.

HTTP Request

POST /v1/transactions/estimate_fee

Body Parameters
Parameter Type Description
assetId string The ID of the asset
amount string The requested amount to transfer
source TransferPeerPath The source of the estimated transaction,
destination DestinationTransferPeerPath The destination of the estimated transaction. For some blockchains it can affect the transaction fee.
operation TransactionOperation [optional] Transaction operation type, the default is "TRANSFER"
Response

Returns an EstimatedTransactionFeeResponse object.

Set Confirmation Threshold by TX ID


set_conf_threshold = client.set_confirmation_threshold_by_tx_id(body)


const setConfThreshold = await fireblocks.setConfirmationThresholdByTxId(body);

The above command returns JSON structured like this:

{
  "success": true,
  "transactions": [
    "string"
  ]
}

Overrides the required number of confirmations for a transaction completion by its transaction ID.

HTTP Request

POST /v1/transactions/{txId}/set_confirmation_threshold

Body Parameters
Parameter Type Description
numOfConfirmations integer The number of transaction's confirmations to be considered COMPLETED
Response

Returns an SetConfirmationsThresholdResponse object.

Set Confirmation Threshold by TX Hash


set_conf_threshold = client.set_confirmation_threshold_by_tx_hash(body)


const setConfThreshold = await fireblocks.setConfirmationThresholdByTxHash(body);

The above command returns JSON structured like this:

{
  "success": true,
  "transactions": [
    "string"
  ]
}

Overrides the required number of confirmations for a transaction completion by its transactions hash.

HTTP Request

POST /v1/txHash/{txHash}/set_confirmation_threshold

Body Parameters
Parameter Type Description
numOfConfirmations integer The number of transaction's confirmations to be considered COMPLETED
Response

Returns an SetConfirmationsThresholdResponse object.

Network Connections

List Network Connections


network_connections = fireblocks.get_network_connections()


const networkConnections = await fireblocks.getNetworkConnections();

The above command returns JSON structured like this:

[
  {
    "id": "string",
    "localChannel": {
      "networkId": "string",
      "name": "string"
    },
    "remoteChannel": {
      "networkId": "string",
      "name": "string"
    }
  }
]

Retrieves all Fireblocks network connections.

HTTP Request

GET /v1/network_connections

Response

Returns an array of NetworkConnection objects.

Retrieve a Network Connection


network_connection = fireblocks.get_network_connection(connectionId)


const network_connection = await fireblocks.getNetworkConnection(connectionId);

The above command returns JSON structured like this:

{
  "id": "string",
  "localChannel": {
    "networkId": "string",
    "name": "string"
  },
  "remoteChannel": {
    "networkId": "string",
    "name": "string"
  }
}

Retrieves a network connection matching the requested connectionId.

HTTP Request

GET /v1/network_connections/{connectionId}

URL Parameters
Parameter Description
connectionId The ID of the network connection
Response

Returns a NetworkConnection object.

Supported Assets

Retrieve all Assets Supported by Fireblocks


supportedAssets = fireblocks.get_supported_assets()


const supportedAssets = await fireblocks.getSupportedAssets();

The above command returns JSON structured like this:

[
  {
    "id": "string",
    "name": "string",
    "type": "BASE_ASSET",
    "contractAddress": "string"
  }
]

Returns all assets supported by Fireblocks.

HTTP Request

GET /v1/supported_assets

Response

Returns an array of AssetTypeResponse.

Smart Transfers

The Fireblocks Assisted Transfer Solution allows counterparties to seamlessly transfer digital assets to each other for settlement.

List Transfer Tickets


ticketId = fireblocks.get_transfer_tickets()


const ticketId = await fireblocks.getTransferTickets();

The above command returns JSON structured like this:

[
  {
    "ticketId": "string",
    "externalTicketId": "string",
    "status": "OPEN",
    "description": "string",
    "terms": [
      {
        "termId": "string",
        "txId": "string",
        "networkConnectionId": "string",
        "outgoing": false,
        "amount": "string",
        "asset": "string",
        "status": "OPEN",
        "description": "string"
      }
    ]
  }
]

List all Smart Transfer tickets.

GET /v1/transfer_tickets

Response

Returns an array TransferTickets objects.

Submit a new Transfer Ticket


ticketId = fireblocks.create_transfer_ticket(terms, external_ticket_id, description)

const payload: CreateTransferTicketArgs = {
    externalTicketId: ticketId,
    terms: [
      {
        networkConnectionId: connId,
        outgoing: true,
        asset: outgoingAsset,
        amount: String(outgoingAmount)
      },
      {
        networkConnectionId: connId,
        asset: incomingAsset,
        amount: String(incomingAmount)
      }
    ]
    description: "Created by fireblocks SDK"
};

const ticketId = await fireblocks.createTransferTicket(payload);

The above command returns JSON structured like this:

{
  "ticketId": "string"
}

This endpoint creates a new transfer ticket between 2 parties on the Fireblocks network.

HTTP Request

POST /v1/transfer_tickets

Body Parameters
Parameter Type Description
terms List of the TransferTicketTerms The terms of the transfer ticket
externalTicketId string [optional] Ticket ID on customer's OMS platform
description string [optional] Custom information that can be added to the ticket
Response

Returns a newly created ticket ID.

Retrieve a Transfer Ticket


ticketId = fireblocks.get_transfer_ticket_by_id(ticket_id)


const ticketId = await fireblocks.getTransferTicketById(ticketId);

The above command returns JSON structured like this:

{
  "ticketId": "string",
  "externalTicketId": "string",
  "status": "OPEN",
  "description": "string",
  "terms": [
    {
      "termId": "string",
      "txId": "string",
      "networkConnectionId": "string",
      "outgoing": false,
      "amount": "string",
      "asset": "string",
      "status": "OPEN",
      "note": "string"
    }
  ]
}

Retrieve a transfer ticket.

GET /v1/transfer_tickets/{ticketId}

URL Parameters
Parameter Description
ticketId The ID of the transfer ticket
Response

Returns a TransferTicket object.

Retrieve a Term of a Transfer Ticket


ticketId = fireblocks.get_transfer_ticket_term(ticket_id, term_id)


const ticketId = await fireblocks.getTransferTicketTerm(ticketId, termId);

The above command returns JSON structured like this:

{
  "termId": "string",
  "txId": "string",
  "networkConnectionId": "string",
  "outgoing": false,
  "amount": "string",
  "asset": "string",
  "status": "OPEN",
  "note": "string"
}

Retrieves a term of a transfer ticket.

GET /v1/transfer_tickets/{ticketId}/{termId}

URL Parameters
Parameter Description
ticketId The ID of the transfer ticket
termId The ID of the term within the ticket
Response

Returns a TransferTicketTerm object.

Cancel a Transfer Request


ticketId = fireblocks.cancel_transfer_ticket(ticket_id)


const ticketId = await fireblocks.cancelTransferTicket(ticketId);

The above command returns 200 (OK)

POST /v1/transfer_tickets/{ticketId}/cancel

URL Parameters
Parameter Description
ticketId The ID of the transfer ticket to cancel
Response

Returns 200 on success.

Make a Transfer from a Transfer Term Context


ticketId = fireblocks.execute_ticket_term(ticket_id, term_id, source)


const ticketId = await fireblocks.executeTicketTerm(ticketId, termId, source);

The above command returns 200 (OK)

POST /v1/transfer_tickets/{ticketId}/{termId}/transfer

URL Parameters
Parameter Description
ticketId The ID of the transfer ticket
termId The ID of the term within the transfer ticket to fulfill
Body Parameters
Parameter Type Description
source TransferPeerPath [optional] If no source will be provided, the source vault account will be the one associated with the network connection
Response

Returns 200 on success.

Gas Station

Fireblocks provides the Gas Station servce to fuel with ETH your Ethereum addresses with ERC20 tokens deposits.

Retrieve your Gas Station Settings





const gasStationInfo = await fireblocks.gasStationInfo();

The above command returns JSON structured like this:

{
  "balance": {
    "ETH": "string"
  },
  "configuration": {
    "gasThreshold": "string",
    "gasCap": "string",
    "maxGasPrice": "string"
  }
}

Retrieves the settings of your Gas Station.

GET /v1/gas_station

Response

Returns a GasStationInfo object.

Edit your Gas Station settings





const gasStation = await fireblocks.setGasStationConfiguration(gasThreshold, gasCap, maxGasPrice)

The above command returns JSON structured like this:

{
  "balance": {
    "ETH": "string"
  },
  "configuraiton" :{
    "gasCap": "string",
    "gasThreshold": "string",
    "maxGasPrice": "string"
  }
}

Configure your Gas Station's settings.

PUT /v1/gas_station/configuration

Body Parameters
Parameter Type Description
gasThreshold string Below this ETH balane the address will be funded up until gasCap value, in ETH units
gasCap string Up to this level the address will be funded with ETH, in ETH units
maxGasPrice string The funding transaction will be sent with this maximum value gas price, in Gwei units
Response

Returns a GasStationConfiguration object.

Users

This provides the visibility of the users and their details in your workspace.
Please note that this endpoint is available only for API keys with Admin permissions.

Retrieve all users


users = fireblocks.get_users()


const users = await fireblocks.getUsers();

The above command returns JSON structured like this:

{
  "users": [
    {
      "id": "string",
      "firstName": "string",
      "lastName": "string",
      "role": "string",
      "email": "string",
      "enabled": true
    }
  ]
}

Retrieves the list of all users in the workspace.

GET /v1/users

Response

Returns a list of Users object.

Data Objects

Here you can find a description of all the objects expected and returned by the endpoints described above.

Vault Objects

CreateVaultAssetResponse

Parameter Type Description
id string The ID of the Vault Account
address string Address of the asset in a Vault Account, for BTC/LTC the address is in Segwit (Bech32) format, cash address format for BCH
legacyAddress string Legacy address format for BTC/LTC/BCH
tag string Destination tag for XRP, used as memo for EOS/XLM
eosAccountName string Returned for EOS, the account name

VaultAsset

Parameter Type Description
id string The ID of the asset
total string The total wallet balance.
balance string Deprecated - replaced by "total"
available string Funds available for transfer. Equals the blockchain balance minus any locked amount
pending string The cumulative balance of all transactions pending to be cleared
staked string Staked funds, returned only for DOT
frozen string Frozen by the AML policy in your workspace
lockedAmount string Funds in outgoing transactions that are not yet published to the network
totalStakedCPU string [optional] Deprecated
totalStakedNetwork string [optional] Deprecated
selfStakedCPU string [optional] Deprecated
selfStakedNetwork string [optional] Deprecated
pendingRefundCPU string [optional] Deprecated
pendingRefundNetwork string [optional] Deprecated
blockHeight string The height (number) of the block of the balance
blockHash string The hash of the block of the balance

VaultAccountAssetAddress

Parameter Type Description
assetId string The ID of the asset
address string Address of the asset in a Vault Account, for BTC/LTC the address is in Segwit (Bech32) format, for BCH cash format
legacyAddress string For BTC/LTC/BCH the legacy format address
description string Description of the address
tag string Destination tag for XRP, used as memo for EOS/XLM, for Signet/SEN it is the Bank Transfer Description
type string Address type
customerRefId string [optional] The ID for AML providers to associate the owner of funds with transactions
bip44AddressIndex number The address_index in the derivation path of this address based on BIP44

CreateAddressResponse

Parameter Type Description
address string Address of the asset in a Vault Account, for BTC/LTC the address is in Segwit (Bech32) format, cash address format for BCH
legacyAddress string Legacy address format for BTC/LTC/BCH
tag string Destination tag for XRP, used as memo for EOS/XLM
bip44AddressIndex number The address_index in the derivation path of this address based on BIP44

VaultAccount

Parameter Type Description
id string The ID of the Vault Account
name string Name of the Vault Account
hiddenOnUI boolean Specifies whether this vault account is visible in the web console or not
customerRefId string [optional] The ID for AML providers to associate the owner of funds with transactions
autoFuel boolean Specifies whether this account's Ethereum address is auto fueled by the Gas Station or not
assets array of VaultAsset List of assets under this Vault Account

PublicKey

Parameter Type Description
publicKey sring The requested public key
algorithm string One of the SigningAlgorithms
derivationPath array of numbers For BIP32 derivation used to retrieve the public key

Internal/External Wallets

WalletAsset

Parameter Type Description
id string The ID of the asset
balance string The balance of the wallet
lockedAmount string Locked amount in the wallet
status ConfigChangeRequestStatus Status of the Internal Wallet
activationTime string The time the wallet will be activated in case wallets activation posponed according to workspace definition
address string The address of the wallet
tag string Destination tag (for XRP, used as memo for EOS/XLM) of the wallet.

ExternalWalletAsset

Parameter Type Description
id string The ID of the asset
status ConfigChangeRequestStatus Status of the External Wallet
activationTime string The time the wallet will be activated in case wallets activation posponed according to workspace definition
address string The address of the wallet
tag string Destination tag (for XRP, used as memo for EOS/XLM) of the wallet, for SEN/Signet used as Bank Transfer Description

UnmanagedWallet

Parameter Type Description
id string The ID of the Unmanaged Wallet
name string Name of the Wallet Container
customerRefId string [optional] The ID for AML providers to associate the owner of funds with transactions
assets array of WalletAsset Array of the assets available in the unmanaged wallet

ExternalWallet

Parameter Type Description
id string The ID of the Unmanaged Wallet
name string Name of the Wallet Container
customerRefId string [optional] The ID for AML providers to associate the owner of funds with transactions
assets array of ExternalWalletAsset Array of the assets available in the exteral wallet

Exchange Objects

ExchangeAccount

Parameter Type Description
id string The ID of the exchange account to return
type ExchangeType
name string Display name of the exchange account
status ConfigChangeRequestStatus Status of the exchange account connection
assets array of ExchangeAsset Assets in the account
isSubaccount boolean True if the account is a subaccount in an exchange
mainAccountId string The of the exchange main account
tradingAccounts array of TradingAccount Trading accounts under this exchange account
fundableAccountType TradingAccountType The internal account that is used for deposit or withdrawals of this exchange main or sub account

ExchangeAsset

Parameter Type Description
id string The ID of the exchange account to return
total string The total balance of the asset in the exchange account
available string The balance that can be withdrawan from the exchange account or moved to a different account
lockedAmount string Locked amount in the account
balance string Deprecated - replaced by "total"

ExchangeType

Parameter Type Description
type string [BITTREX, COINBASEPRO, BINANCE, BINANCEUS, BITMEX, KRAKEN, GEMINI, BITFINEX, BITSTAMP, POLONIEX, DERIBIT, LIQUID, HUOBI, BITHUMB, OKEX, OKCOIN, HITBTC, KORBIT, SEEDCX, BITSO]

TradingAccount

Parameter Type Description
type TradingAccountType The specific trading account under the exchange account
assets array of ExchangeAsset Assets in the trading account

TradingAccountType

Parameter Type Description
type string [SPOT, FUTURES, MARGIN, FUNDING, OPTIONS, EXCHANGE, COINED_MARGINED_SWAP, USDT_FUTURES, COIN_FUTURES, USDT_ISOLATED_MARGINED_SWAP, USDT_CROSS_MARGINED_SWAP, FUNDUBLE]

Transactions

TransferPeerPath

Parameter Type Description
type string [ VAULT_ACCOUNT, EXCHANGE_ACCOUNT, FIAT_ACCOUNT, GAS_STATION ]
id string The ID of the peer

DestinationTransferPeerPath

Parameter Type Description
type string [ VAULT_ACCOUNT, EXCHANGE_ACCOUNT, INTERNAL_WALLET, EXTERNAL_WALLET, ONE_TIME_ADDRESS, NETWORK_CONNECTION, FIAT_ACCOUNT, COMPOUND ]
id string The peer ID (not needed for ONE_TIME_ADDRESS)
oneTimeAddress OneTimeAddress Destination address

CreateTransactionResponse

Parameter Type Description
id string The ID of the transaction
status TransactionStatus Status of the transaction

CancelTransactionResponse

Parameter Type Description
success boolean True if the cancellation succeeded

TransferPeerPathResponse

Parameter Type Description
type string [ VAULT_ACCOUNT, EXCHANGE_ACCOUNT, INTERNAL_WALLET, EXTERNAL_WALLET, ONE_TIME_ADDRESS, NETWORK_CONNECTION, FIAT_ACCOUNT, COMPOUND, UNKNOWN ]
id string The ID of the exchange account to return
name string The name of the exchange account
subType string

TransactionDetails

Parameter Type Description
id string ID of the transaction
assetId string Transaction asset
source TransferPeerPathResponse Source of the transaction
destination TransferPeerPathResponse Destination of the transaction
requestedAmount number The amount requested by the user
amountInfo AmountInfo Details of the transaction's amount in string format
feeInfo FeeInfo Details of the transaction's fee in string format
amount number If the transfer is a withdrawal from an exchange, the actual amount that was requested to be transferred. Otherwise, the requested amount
netAmount number The net amount of the transaction, after fee deduction
amountUSD number The USD value of the requested amount
serviceFee number The total fee deducted by the exchange from the actual requested amount (serviceFee = amount - netAmount)
treatAsGrossAmount boolean For outgoing transactions, if true, the network fee is deducted from the requested amount
networkFee number The fee paid to the network
createdAt number Unix timestamp
lastUpdated number Unix timestamp
status TransactionStatus The current status of the transaction
txHash string Blockchain hash of the transaction
index number For UTXO based assets this is the vOut, for Ethereum based, this is the index of the event of the contract call
subStatus TransactionSubStatus More detailed status of the transaction
sourceAddress string For account based assets only, the source address of the transaction
destinationAddress string Address where the asset were transfered
destinationAddressDescription string Description of the address
destinationTag string Destination tag (for XRP, used as memo for EOS/XLM) or Bank Transfer Description for Signet/SEN
signedBy array of strings Signers of the transaction
createdBy string Initiator of the transaction
rejectedBy string User ID of the user that rejected the transaction (in case it was rejected)
addressType string [ ONE_TIME, WHITELISTED ]
note string Custome note of the transaction
exchangeTxId string If the transaction originated from an exchange, this is the exchange tx ID
feeCurrency string The asset which was taken to pay the fee (ETH for ERC-20 tokens, BTC for Tether Omni)
operation TransactionOperation Default operation is "TRANSFER"
amlScreeningResult AmlScreeningResult The result of the AML screening
customerRefId string The ID for AML providers to associate the owner of funds with transactions
numOfConfirmations number The number of confirmations of the transaction. The number will increase until the transaction will be considered completed according to the confirmation policy.
networkRecords array of NetworkRecord objects Transaction on the Fireblocks platform can aggregate several blockchain transactions, in such a case these records specify all the transactions that took place on the blockchain.
replacedTxHash string In case of an RBF transaction, the hash of the dropped transaction
externalTxId string Unique transaction ID provided by the user
destinations array of DestinationsResponse For UTXO based assets, all outputs specified here
blockInfo BlockInfo The information of the block that this transaction was mined in, the blocks's hash and height
authorizationInfo AuthorizationInfo The information about your Transaction Authorization Policy, more info on the TAP can be found in this Help Center article
signedMessages array of SignedMessage objects A list of signed messages returned for raw signing
extraParameters JSON object Protocol / operation specific parameters.

TransactionOperation

Parameter Type Description
operation string [ TRANSFER, RAW, CONTRACT_CALL, MINT, BURN, SUPPLY_TO_COMPOUND, REDEEM_FROM_COMPOUND ]

BlockInfo

Parameter Type Description
blockHeight string The height (number) of the block the transaction was mined in
blockHash string The hash of the block the transaction was mined in

SignedMessage

Parameter Type Description
content string The message for signing (hex-formatted)
algorithm string The algorithm that was used for signing, one of the SigningAlgorithms
derivationPath array of numbers BIP32 derivation path of the signing key. E.g. [44,0,46,0,0]
signature dictionary The message signature
publicKey string Signature's public key that can be used for verification.

NetworkFee

Parameter Type Description
feePerByte string [optional] For UTXOs
gasPrice string [optional] For Ethereum assets (ETH and Tokens)
networkFee string [optional] All other assets

TransactionFee

Parameter Type Description
feePerByte string [optional] For UTXOs,
gasPrice string [optional] For Ethereum assets (ETH and Tokens)
gasLimit string [optional] For Ethereum assets (ETH and Tokens), the limit for how much can be used
networkFee string [optional] Transaction fee

EstimatedTransactionFeeResponse

Parameter Type Description
low TransactionFee Transactions with this fee will probably take longer to be mined
medium TransactionFee Average transactions fee
high TransactionFee Transactions with this fee should be mined the fastest

AmountInfo

Parameter Type Description
amount string If the transfer is a withdrawal from an exchange, the actual amount that was requested to be transferred. Otherwise, the requested amount
requestedAmount string The amount requested by the user
netAmount string The net amount of the transaction, after fee deduction
amountUSD string The USD value of the requested amount

FeeInfo

Parameter Type Description
networkFee string The fee paid to the network
serviceFee string The total fee deducted by the exchange from the actual requested amount (serviceFee = amount - netAmount)

SetConfirmationsThresholdResponse

Parameter Type Description
success boolean
transactions array of strings txIds of the transactions

AmlScreeningResult

Parameter Type Description
provider string The AML service provider
payload string The response of the AML service provider

RawMessageData

Parameter Type Description
messages array of UnsignedRawMessage objects The messages that should be signed
algorithm string [optional] The algorithm which will be used to sign the transaction, one of the SigningAlgorithms

UnsignedRawMessage

Parameter Type Description
content string The message to be signed in hex format encoding
bip44AddressIndex number [optional] BIP44 address_index path level
bip44change number [optional] BIP44 change path level
The 2 fields above complement the derivation path given the source id and asset were provided in the transaction body request.
In case none of the above was provided, please specify the derivation path.
derivationPath array of numbers [optional] Should be passed only if asset and source were not specified

SigningAlgorithm

Parameter Type Description
algorithm string [ MPC_ECDSA_SECP256K1, MPC_ECDSA_SECP256R1, MPC_EDDSA_ED25519 ]

OneTimeAddress

Parameter Type Description
address string Transfer destination address
tag string Transfer destination tag (for Ripple, 'memo' for EOS/XLM), for SEN/Signet used as Bank Transfer Description

TransactionRequestDestination

Parameter Type Description
amount string The amount to be sent to this destination
destination DestinationTransferPeerPath The specific destination

InputsSelection

Parameter Type Description
inputsToSpend Array Array of Inputs
inputsToExclude Array Array of Inputs

Input

Parameter Type Description
txHash string txHash
index string vOut of the txHash

UnspentInputsData

Parameter Type Description
txHash string txHash
index string vOut of the txHash
address string The destination address of this input
amount string The amount of this input
confirnation number Number of confirmation of the transaction of this input
status string The status is based on the status of the transaction

DestinationsResponse

Parameter Type Description
amount string The amount to be sent to this destination
destination TransferPeerPathResponse Destination of the transaction
amountUSD number The USD value of the requested amount
destinationAddress string Address where the asset were transfered
destinationAddressDescription string Description of the address
amlScreeningResult AmlScreeningResult The result of the AML screening
customerRefId string The ID for AML providers to associate the owner of funds with transactions

AddressStatus

Parameter Type Description
isValid boolean Returns "false" if the address is in a wrong format
isActive boolean Returns "false" if the address doesn't have enough balance or wasn't activate
requiresTag boolean Returns "true" if the address requires tag when used as a transaction destination

AuthorizationInfo

Parameter Type Description
allowOperatorAsAuthorizer boolean Set to "true" if the intiator of the transaction can be one of the approvers
logic string "AND" or "OR", this is the logic that is applied between the different authorization groups listed below
groups list of AuthorizationGroups The list of authorization groups and users that are required to approve this transaction. The logic applied between the different groups is the “logic” field above. Each element in the response is the user ID (the can found see via the users endpoint) and theirApprovalStatus

AuthorizationGroup

Parameter Type Description
th number The threshold of required approvers in this authorization group
users list of users The list of users that the threshold number is applied to for transaction approval. Each user in the response is a "key:value" where the key is the user ID (the can found see via the users endpoint) and the value is the theirApprovalStatus.

ApprovalStatus

Parameter Type Description
approval string [ PENDING_AUTHORIZATION, APPROVED, REJECTED, NA ]

Network Objects

NetworkRecord

Parameter Type Description
source TransferPeerPathResponse Source of the transaction
destination TransferPeerPathResponse Destination of the transaction
txHash string Blockchain hash of the transaction
networkFee number The fee paid to the network
assetId string Transaction asset
netAmount number The net amount of the transaction, after fee deduction
status NetworkStatus Status of the blockchain transaction
type string Type of the operation
destinationAddress string Destination address
sourceAddress string For account based assets only, the source address of the transaction

NetworkConnection

Parameter Type Description
id string The ID of the Network Connection
localChannel Channel Local channel ID
remoteChannel Channel Remote channel ID

Channel

Parameter Type Description
networkId string 8 characters ID of the channel
name string The name of the channel

Fiat Account Objects

FiatAccount

Parameter Type Description
id string The ID of the account
type string [ SIGNET, SILVERGATE ]
name string Display name of the fiat account
address string The address of the account
assets Array of FiatAssets Array of the assets under the account

FiatAsset

Parameter Type Description
id string The ID of the asset
balance string The balance of the asset

Supported Assets Object

AssetTypeResponse

Parameter Type Description
id string The ID of the asset
name string The name of the asset
type string [ BASE_ASSET, ETH_CONTRACT, FIAT ]
contractAddress string Contract address for ERC-20 smart contracts

Smart Transfers Objects

TransferTicket

Parameter Type Description
ticketId string Transfer ticket ID on the Fireblocks platform
terms array of TransferTicketTerms All the terms of the transfer ticket
externalTicketId string [optional] Ticket ID on customer's internal system. Can be used for reference
description string [optional] Custom string set by the user
status TransferTicketStatus The current status of the transfer ticket

TransferTicketTerm

Parameter Type Description
networkConnectionId string The Fireblocks network connection on which this term should be fulfilled
outgoing boolean True means that the term is from the initiator of the ticket
asset string The asset of term that was agreed on
amount string The amount of the asset that should be transferred
note string [optional] Custom note that can be added to the term

TransferTicketTermResponse

Parameter Type Description
termId string The ID of the term within the ticket context, a running index.
networkConnectionId string The Fireblocks network connection on which this term should be fulfilled
outgoing boolean True means that the term is from the initiator of the ticket
asset string The asset of term that was agreed on
amount string The amount of the asset that should be transferred
txIds array of strings Transactions associated with this term
status TransferTicketTermStatus Status of the term
note string Custom note that can be added to the term

Gas Station Objects

GasStationInfo

Parameter Type Description
balance dictionary A dictionary of an asset and its balance in the Gas Station
configuration GasStationConfiguration The settings of your Gas Station

GasStationConfiguration

Parameter Type Description
gasThreshold string Below this ETH balane the address will be funded up until gasCap value, in ETH units
gasCap string Up to this level the address will be funded with ETH, in ETH units
maxGasPrice string The funding transaction will be sent with this maximum value gas price, in Gwei units

Users

User

Parameter Type Description
id string User ID on the Fireblocks platform
firstName string First name
lastName string Last name
role string The role of the user in the workspace, one of the options as described here
email string The email of the user
enabled boolean The status of the user in the workspace

General Objects

ConfigChangeRequestStatus

Parameter Type Description
status string [ WAITING_FOR_APPROVAL, APPROVED, CANCELLED, REJECTED, FAILED ]

API Co-Signer

Overview

The API Co-Signer is a component that holds an MPC key share of a customer's Fireblocks Vault and a Configuration Change Key for automated signing and approvals. The key share is used to securely sign transactions initiated via the API. The Configuration Change Key is used to approve new unmanaged wallet additions in the Fireblocks Vault.
The API Co-Signer can be provisioned with a Co-Signer Callback Handler, an HTTPS server that receives signing requests from the API Co-Signer and returns to the Co-Signer either an approval or rejection response. For more details on how to handle a Co-Signer request and how to structure your response, please see the Automated Signer Callback section below.
Please refer to this article for Callback Handler setup instruction.

Automated Transaction Flow Diagram

Signing flow

Automated Signer Callback

In case the API Co-Signer is configured with a callback, it will send a POST request to the Callbck Handler, a predefined HTTPS server that should respond with APPROVE, REJECT or IGNORE action. IGNORE can be returned only for transaction authorization or configuration change.

The POST request will contain a JWT encoded message signed with the Co-Signer's private key. The Callback Handler should use the Co-Signer's public key to verify every incoming JWT is signed correctly by the Co-Signer.

The callback response shall be a JWT encoded message signed with the callback handler's private key. The private key must be the one paired with the public key provided to the Co-Signer during setup of the Callback Handler.

This Callback Handler should listen on the endpoints described below and respond accordingly to the needed action.

Transaction Signing Callback Handler

# -*- coding: utf-8 -*-
"""
App runner
"""
# System imports
from pathlib import Path
# Third-party imports
import falcon
import jwt

callback_handler_prikey = None
cosigner_pubkey = None

class JWTTransferRequest(object):
    def on_post(self, req, resp):
        raw_req = req.bounded_stream.read()
        req = jwt.decode(raw_req, cosigner_pubkey, algorithms=["RS256"])
        resp.body = jwt.encode({'action': 'APPROVE', 'requestId': req['requestId']}, callback_handler_prikey, algorithm="RS256")
        resp.status = falcon.HTTP_200

# Load keys.
f1 = Path("callback_handler.pem")
if f1.is_file(): callback_handler_prikey = f1.read_bytes()
f2 = Path("cosigner_pubkey.pem")
if f2.is_file(): cosigner_pubkey = f2.read_bytes()

# Create falcon app
app = falcon.API()

app.add_route('/v2/tx_sign_request', JWTTransferRequest())
app.add_route('/v2/config_change_sign_request', JWTTransferRequest())

POST /v2/tx_sign_request

Returns a CallbackResponse object.

Parameters sent
Parameter Type Description
requestId string Unique identifier for the call - to be returned in the response
txId string Fireblocks' internal transaction ID
operation string The type of the operation
sourceType string Whether the transfer is from Fireblocks vault or exchange (VAULT or EXCHANGE)
sourceId string The ID of the vault account or the exchange account UUID
destType string The destination of the transaction (VAULT or EXCHANGE or UNMANAGED)
destAddressType string WHITELISTED or ONE_TIME
destId string The ID of the destination
asset string The asset symbol
amount number The amount of the transfer
amountStr string The amount of the transfer in string representation
destAddress string The destination address of the transfer
fee string [optional] The fee of the transaction
note string [optional] The note that is passed with the transaction body request
destinations array of TransactionRequestDestination For UTXO based assets, you can send a single
extraParameters [optional] JSON object Protocol / operation specific parameters

Configuration Approval Callback Handler

POST /v2/config_change_sign_request

Returns a CallbackResponse object.

Parameters sent
Parameter Type Description
requestId string Unique identifier for the call - taken from the request
type string [ UNMANAGED_WALLET, EXCHANGE, FIAT_ACCOUNT ]
extraInfo JSON object Either AddressInfo or ThirdPartyInfo json object.

Co-Signer Data Objects

AddressInfo

Parameter Type Description
subType string [ INTERNAL, EXTERNAL ]
walletName string The name of the wallet as defined in the workspace
walletId string Fireblocks' internal wallet ID
asset string Wallet's asset
address string The address of the asset in the wallet
tag string [optional] For assets that have tag/memo (XRP/EOS/XLM), for SEN/Signet used as Bank Transfer Description

ThirdPartyInfo

Parameter Type Description
subType ThirdPartyType The third party
accountName string The name of the account
accountId string The ID of the account
apiKey string Third party's API key
addresses string [optional] A JSON formated "key":"value" string, where the key is an asset symbol (asset symbols can be retrieved at the supported-assets and the value is its address. There can be multiple entries in the JSON.

CallbackResponse

Parameter Type Description
action string [APPROVE, REJECT, IGNORE]
rejectionReason string Free text of the rejection reason for logging purposes

API Responses

HTTP Status Code

API Error Codes

Error Code HTTP Status Code Constant
1000 400 GET_VAULT_ACCOUNTS_INVALID_PARAMS
1001 500 GET_VAULT_ACCOUNTS_UNEXPECTED_ERROR
1002 400 POST_VAULT_ACCOUNTS_INVALID_PARAMS
1003 500 POST_VAULT_ACCOUNTS_UNEXPECTED_ERROR
1004 400 GET_VAULT_ACCOUNT_BY_ID_NOT_FOUND
1005 500 GET_VAULT_ACCOUNT_BY_ID_UNEXPECTED_ERROR
1006 400 GET_VAULT_ASSET_FAILED_NOT_FOUND
1007 500 GET_VAULT_ASSET_FAILED_UNEXPECTED_ERROR
1008 400 CREATE_VAULT_ASSET_FAILED_INVALID_PARAMS
1009 500 CREATE_VAULT_ASSET_FAILED_UNEXPECTED_ERROR
1010 400 CREATE_VAULT_ASSET_ADDRESS_FAILED_INVALID_PARAMS
1011 500 CREATE_VAULT_ASSET_ADDRESS_FAILED_UNEXPECTED_ERROR
1012 500 GET_VAULT_ASSET_ADDRESS_FAILED_UNEXPECTED_ERROR
1013 400 PUT_VAULT_ACCOUNTS_INVALID_PARAMS
1014 500 PUT_VAULT_ACCOUNTS_UNEXPECTED_ERROR
1015 400 PUT_ADDRESS_ID_INVALID_PARAMS
1016 500 PUT_ADDRESS_ID_UNEXPECTED_ERROR
1017 400 HIDE_VAULT_ACCOUNT_NOT_FOUND
1018 500 HIDE_VAULT_ACCOUNT_SEND_FAILED
1019 400 HIDE_VAULT_ACCOUNT_INVALID_PARAMS
1020 400 UNHIDE_VAULT_ACCOUNT_NOT_FOUND
1021 500 UNHIDE_VAULT_ACCOUNT_SEND_FAILED
1022 400 UNHIDE_VAULT_ACCOUNT_INVALID_PARAMS
1025 400 CREATE_VAULT_ASSET_UNSUPPORTED_ERROR
1026 400 CREATE_VAULT_ASSET_NOT_ALLOWED_ERROR
1027 400 MAX_SPENDABLE_AMOUNT_ASSET_NOT_ALLOWED_ERROR
1028 400 MAX_SPENDABLE_AMOUNT_INVALID_PARAMETERS
1029 500 MAX_SPENDABLE_AMOUNT_INTERNAL_ERROR
1030 500 MAX_SPENDABLE_AMOUNT_UNEXPECTED_ERROR
1031 400 GET_VAULT_ASSETS_BLANCE_INVALID_PARAMETERS
1032 400 GET_VAULT_ASSETS_BLANCE_NOT_FOUND_ERROR
1033 500 GET_VAULT_ASSETS_BLANCE_UNEXPECTED_ERROR
1034 400 CREATE_VAULT_ASSET_FAILED_INVALID_ASSET_TESTNET
1101 500 GET_EXCHANGE_ACCOUNTS_UNEXPECTED_ERROR
1102 500 GET_EXCHANGE_ACCOUNT_BY_ID_UNEXPECTED_ERROR
1103 400 GET_EXCHANGE_ACCOUNT_BY_ID_NOT_FOUND
1104 500 GET_EXCHANGE_ASSET_BY_ID_UNEXPECTED_ERROR
1105 400 GET_EXCHANGE_ASSET_BY_ID_NOT_FOUND
1106 400 INTERNAL_TRANSFER_INVALID_PARAMS
1107 400 INTERNAL_TRANSFER_UNEXPECTED_ERROR
1201 500 GET_INTERNAL_WALLETS_UNEXPECTED_ERROR
1202 400 CREATE_INTERNAL_WALLET_INVALID_PARAMS
1202 500 CREATE_INTERNAL_WALLET_UNEXPECTED_ERROR
1203 500 GET_INTERNAL_WALLET_BY_ID_UNEXPECTED_ERROR
1204 400 GET_INTERNAL_WALLET_BY_ID_INVALID_PARAMS
1205 500 DELETE_INTERNAL_WALLET_BY_ID_UNEXPECTED_ERROR
1206 400 DELETE_INTERNAL_WALLET_BY_ID_INVALID_PARAMS
1207 500 CREATE_INTERNAL_WALLET_ASSET_UNEXPECTED_ERROR
1208 400 CREATE_INTERNAL_WALLET_ASSET_INVALID_PARAMS
1209 400 GET_INTERNAL_WALLET_ASSET_INVALID_PARAMS
1210 500 GET_INTERNAL_WALLET_ASSET_UNEXPECTED_ERROR
1211 400 DELETE_INTERNAL_WALLET_ASSET_INVALID_PARAMS
1212 500 DELETE_INTERNAL_WALLET_ASSET_UNEXPECTED_ERROR
1213 400 CREATE_INTERNAL_WALLET_ASSET_UNSUPPORTED_ERROR
1214 400 CREATE_INTERNAL_WALLET_ASSET_NOT_ALLOWED_ERROR
1215 400 CREATE_INTERNAL_WALLET_ASSET_ALREADY_EXISTS_ERROR
1216 400 CREATE_INTERNAL_WALLET_ASSSET_INVALID_ADDRESS
1301 400 GET_EXTERNAL_WALLETS_UNEXPECTED_ERROR
1302 400 CREATE_EXTERNAL_WALLET_INVALID_PARAMS
1302 500 CREATE_EXTERNAL_WALLET_UNEXPECTED_ERROR
1303 500 GET_EXTERNAL_WALLET_BY_ID_UNEXPECTED_ERROR
1304 400 GET_EXTERNAL_WALLET_BY_ID_INVALID_PARAMS
1305 500 DELETE_EXTERNAL_WALLET_BY_ID_UNEXPECTED_ERROR
1306 400 DELETE_EXTERNAL_WALLET_BY_ID_INVALID_PARAMS
1307 500 CREATE_EXTERNAL_WALLET_ASSET_UNEXPECTED_ERROR
1308 400 CREATE_EXTERNAL_WALLET_ASSET_INVALID_PARAMS
1309 400 GET_EXTERNAL_WALLET_ASSET_INVALID_PARAMS
1310 500 GET_EXTERNAL_WALLET_ASSET_UNEXPECTED_ERROR
1311 400 DELETE_EXTERNAL_WALLET_ASSET_INVALID_PARAMS
1312 500 DELETE_EXTERNAL_WALLET_ASSET_UNEXPECTED_ERROR
1313 400 CREATE_EXTERNAL_WALLET_ASSET_UNSUPPORTED_ERROR
1314 400 CREATE_EXTERNAL_WALLET_ASSET_NOT_ALLOWED_ERROR
1315 400 CREATE_EXTERNAL_WALLET_ASSET_ALREADY_EXISTS_ERROR
1316 400 CREATE_EXTERNAL_WALLET_ASSET_INVALID_ADDRESS
1401 400 CREATE_TRANSACTION_UNSUPPORTED_ACTION
1402 400 CREATE_TRANSACTION_SOURCE_BALANCE
1403 400 CREATE_TRANSACTION_DESTINATION_BALANCE
1404 500 CREATE_TRANSACTION_UNEXPECTED_ERROR
1405 400 GET_TRANSACTION_NOT_FOUND
1406 400 CANCEL_TRANSACTION_FAILED
1408 400 GET_TRANSACTION_INVALID_PARAMS
1409 400 CREATE_TRANSACTION_INVALID_PARAMS
1410 400 CREATE_TRANSACTION_UNMANAGED_WALLET_CONTAINER_NOT_FOUND
1411 400 CREATE_TRANSACTION_UNMANAGED_WALLET_NOT_FOUND
1412 400 CREATE_TRANSACTION_UNMANAGED_WALLET_SUSPENDED
1421 400 SET_CONFIRMATION_THRESHOLD_FAILED_TRANSACTIONS
1422 400 SET_CONFIRMATION_THRESHOLD_FAILED_TX_HASH
1423 400 GET_TRANSACTIONS_BY_TXHASH_NOT_FOUND
1424 400 CREATE_TRANSACTION_DESTINATION_RIPPLE_INVALID
1425 400 CREATE_TRANSACTION_RIPPLE_MISSING_TAG
1426 400 UNFREEZE_TRANSACTION_FAILED
1427 400 CREATE_TRANSACTION_SOURCE_ERROR
1428 400 CREATE_TRANSACTION_DESTINATION_ERROR
1429 400 VALIDATE_ADDRESS_INVALID_PARAMETER
1430 500 VALIDATE_ADDRESS_UNEXPECTED_ERROR
1431 400 VALIDATE_ADDRESS_NOT_FOUND
1432 400 CREATE_TRANSACTION_INVALID_AMOUNT
1433 400 CREATE_TRANSACTION_INVALID_DEST_TAG
1434 400 FREEZE_TRANSACTION_FAILED
1435 400 LIST_UNSPENTS_UNKNOWN_ASSET
1436 400 LIST_UNSPENTS_UNEXPECTED_ERROR
1437 400 RESTRICTED_SOURCE
1440 400 DROP_TRANSACTION_FAILED
1441 400 GAS_PRICE_TOO_LOW_FOR_RBF
1443 400 RBF_TRANSACTION_ALREADY_MINED
1501 500 GET_SUPPORTED_ASSETS_UNEXPECTED_ERROR
1601 400 GET_CONNECTION_BY_ID_NOT_FOUND
1602 400 GET_CONNECTION_BY_ID_UNAUTHORIZED
1702 500 GET_FIAT_ACCOUNT_BY_ID_UNEXPECTED_ERROR
1703 400 GET_FIAT_ACCOUNT_BY_ID_NOT_FOUND
1705 400 GET_FIAT_ASSET_BY_ID_NOT_FOUND
1706 400 REDEEM_TO_DDA_INVALID_PARAMS
1707 400 REDEEM_TO_DDA_UNEXPECTED_ERROR
1708 400 DEPOSIT_FROM_DDA_INVALID_PARAMS
1709 400 DEPOSIT_FROM_DDA_UNEXPECTED_ERROR
1801 500 TRANSFER_ASSIST_SERVICE_ERROR
1901 400 ESTIMATE_FEES_UNKNOWN_ASSET
1902 400 ESTIMATE_FEES_INVALID_ASSET
1903 400 ESTIMATE_FEES_CALCULATING_FAILED
1904 400 ESTIMATE_FEES_INVALID_PARAMS
1905 400 ESTIMATE_FEES_INSUFFICIENT_FUNDS
2001 500 PUBLIC_KEY_UNEXPECTED_ERROR
2002 400 PUBLIC_KEY_NOT_FOUND
2101 400 GAS_STATION_INVALID_PARAMS
2102 500 GAS_STATION_UNEXPECTED_ERROR
2103 400 AML_INVALID_PARAMS
2104 500 AML_UNEXPECTED_ERROR
2105 400 AML_POLICY_NOT_FOUND
2106 400 AML_PROVIDER_CONFIGURATION_NOT_FOUND
2201 400 ALLOCATE_UNKOWN_ASSET
2202 400 ALLOCATED_ACCOUNT_NOT_FOUND
2203 500 ALLOCATE_INTERNAL_ERROR
2204 400 ALLOCATE_TO_FEE_BANK_PROHIBITED
9001 400 INVALID_CUSTOMER_REF_ID
9002 401 ACCESS_DENIED_FOR_IP
9003 400 IDEMPOTENCY_KEY_INVALID
9005 400 IDEMPOTENCY_KEY_IN_PROGRESS

Webhook

Overview

Setting a webhook will allow you to get notifications for events that happen on your Fireblocks workspace. You can receive notifications on events in your workspace such as incoming/outgoing transactions, transactions status update, new vault accounts, new wallets, new external/internal addresses and many more.

In order to connect a Webhook to your Fireblocks workspace please contact Fireblocks Support and provide your Webhook's URL. Once your Webhook is connected to your Fireblocks workspace, you will start receiving notification on events in that workspace. All events will be sent with the following headers (the public key for verifying the signature can be found here):

Fireblocks will send a POST request to the URL(s) associated with the workspace and expect a 200 response. If no response is received, Fireblocks will resend the request several more times with an increasing delay between each attempt, the retry attemps will be taken after [ 15, 45, 105,225, 465, 945, 1905, 3825, 7665, 15345 ] seconds.

On the language tabs you can find examples on how to setup up the server and verify the signature header of the request.

Event Types

Below you can find the list of all events your webhook will receive notifications for.

# -*- coding: utf-8 -*-
"""
App runner
"""
# Third-party imports
import falcon
import json
import rsa
import base64

FIREBLOCKS_PUBLIC_KEY = """
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0+6wd9OJQpK60ZI7qnZG
jjQ0wNFUHfRv85Tdyek8+ahlg1Ph8uhwl4N6DZw5LwLXhNjzAbQ8LGPxt36RUZl5
YlxTru0jZNKx5lslR+H4i936A4pKBjgiMmSkVwXD9HcfKHTp70GQ812+J0Fvti/v
4nrrUpc011Wo4F6omt1QcYsi4GTI5OsEbeKQ24BtUd6Z1Nm/EP7PfPxeb4CP8KOH
clM8K7OwBUfWrip8Ptljjz9BNOZUF94iyjJ/BIzGJjyCntho64ehpUYP8UJykLVd
CGcu7sVYWnknf1ZGLuqqZQt4qt7cUUhFGielssZP9N9x7wzaAIFcT3yQ+ELDu1SZ
dE4lZsf2uMyfj58V8GDOLLE233+LRsRbJ083x+e2mW5BdAGtGgQBusFfnmv5Bxqd
HgS55hsna5725/44tvxll261TgQvjGrTxwe7e5Ia3d2Syc+e89mXQaI/+cZnylNP
SwCCvx8mOM847T0XkVRX3ZrwXtHIA25uKsPJzUtksDnAowB91j7RJkjXxJcz3Vh1
4k182UFOTPRW9jzdWNSyWQGl/vpe9oQ4c2Ly15+/toBo4YXJeDdDnZ5c/O+KKadc
IMPBpnPrH/0O97uMPuED+nI6ISGOTMLZo35xJ96gPBwyG5s2QxIkKPXIrhgcgUnk
tSM7QYNhlftT4/yVvYnk0YcCAwEAAQ==
-----END PUBLIC KEY-----
"""

signature_pub_key = rsa.PublicKey.load_pkcs1_openssl_pem(FIREBLOCKS_PUBLIC_KEY)

class RequestBodyMiddleware(object):
    def process_request(self, req, resp):
        req.body = req.bounded_stream.read()

class AuthMiddleware(object):
    def process_request(self, req, resp):
        signature = req.get_header('Fireblocks-Signature')

        if signature is None:
            raise falcon.HTTPUnauthorized('Signature required')

        if not self._signature_is_valid(req.body, signature):
            raise falcon.HTTPUnauthorized('Invalid signature')

    def _signature_is_valid(self,  body, signature):
        try:
            hashing_alg = rsa.verify(body, base64.b64decode(signature), signature_pub_key)
            return hashing_alg == "SHA-512"
        except rsa.pkcs1.VerificationError:
            return False

class DummyRequest(object):
    def on_post(self, req, resp):
        obj = json.loads(req.body.decode("utf-8"))
        print(obj)
        resp.status = falcon.HTTP_201


# Create falcon app
app = falcon.API(
    middleware=[
        RequestBodyMiddleware(),
        AuthMiddleware()
    ]
)

app.add_route('/webhook', DummyRequest())


if __name__ == '__main__':
    from wsgiref import simple_server  # NOQA
    httpd = simple_server.make_server('127.0.0.1', 8000, app)
    httpd.serve_forever()
const crypto = require("crypto");
const express = require("express");
const bodyParser = require('body-parser')

const port = 3000;

const publicKey = `-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0+6wd9OJQpK60ZI7qnZG
jjQ0wNFUHfRv85Tdyek8+ahlg1Ph8uhwl4N6DZw5LwLXhNjzAbQ8LGPxt36RUZl5
YlxTru0jZNKx5lslR+H4i936A4pKBjgiMmSkVwXD9HcfKHTp70GQ812+J0Fvti/v
4nrrUpc011Wo4F6omt1QcYsi4GTI5OsEbeKQ24BtUd6Z1Nm/EP7PfPxeb4CP8KOH
clM8K7OwBUfWrip8Ptljjz9BNOZUF94iyjJ/BIzGJjyCntho64ehpUYP8UJykLVd
CGcu7sVYWnknf1ZGLuqqZQt4qt7cUUhFGielssZP9N9x7wzaAIFcT3yQ+ELDu1SZ
dE4lZsf2uMyfj58V8GDOLLE233+LRsRbJ083x+e2mW5BdAGtGgQBusFfnmv5Bxqd
HgS55hsna5725/44tvxll261TgQvjGrTxwe7e5Ia3d2Syc+e89mXQaI/+cZnylNP
SwCCvx8mOM847T0XkVRX3ZrwXtHIA25uKsPJzUtksDnAowB91j7RJkjXxJcz3Vh1
4k182UFOTPRW9jzdWNSyWQGl/vpe9oQ4c2Ly15+/toBo4YXJeDdDnZ5c/O+KKadc
IMPBpnPrH/0O97uMPuED+nI6ISGOTMLZo35xJ96gPBwyG5s2QxIkKPXIrhgcgUnk
tSM7QYNhlftT4/yVvYnk0YcCAwEAAQ==
-----END PUBLIC KEY-----`.replace(/\\n/g, "\n");

const app = express();

app.use(bodyParser.json());

app.post("/webhook", (req, res) => {
    const message = JSON.stringify(req.body);
    const signature = req.headers("Fireblocks-Signature");

    const verifier = crypto.createVerify('RSA-SHA512');
    verifier.write(message);
    verifier.end();

    const isVerified = verifier.verify(publicKey, signature, "base64");
    console.log("Verified:", isVerified);

    res.send("ok");
});

app.listen(port, () => {
    console.log(`Webhook running at http://localhost:${port}`);
});

Event Data Description
TRANSACTION_CREATED TransactionCreated Sent upon any new transaction identified in the workspace
TRANSACTION_STATUS_UPDATED TransactionStatusUpdated Sent upon any change in the status of a transaction or number of confirmations update
TRANSACTION_APPROVAL_STATUS_UPDATED TransactionApprovalStatusUpdated Sent with every approval based on the Transaction Authorization Policy
VAULT_ACCOUNT_ADDED VaultAccountAdded Sent upon addition of a new vault account in the workspace
VAULT_ACCOUNT_ASSET_ADDED VaultAccountAssetAdded Sent upon addition of a new asset under a vault account
INTERNAL_WALLET_ASSET_ADDED InternalWalletAssetAdded Sent upon addition of a new asset under an internal wallet
EXTERNAL_WALLET_ASSET_ADDED ExternalWalletAssetAdded Sent upon addition of a new asset under an external wallet
EXCHANGE_ACCOUNT_ADDED ExchangeAccountAdded Sent upon addition of a new exchange account
FIAT_ACCOUNT_ADDED FiatAccountAdded Sent upon addition of a new fiat account
NETWORK_CONNECTION_ADDED NetworkConnectionAdded Sent upon addition of a new network connection

Event Objects

TransactionCreated

Parameter Type Description
type string TRANSACTION_CREATED
tenantId string Unique id of your Fireblocks' workspace
timestamp number Timestamp in milliseconds
data TransactionDetails All the transaction information

TransactionStatusUpdated

Parameter Type Description
type string TRANSACTION_STATUS_UPDATED
tenantId string Unique id of your Fireblocks' workspace
timestamp number Timestamp in milliseconds
data TransactionDetails All the transaction information

TransactionApprovalStatusUpdated

Parameter Type Description
type string TRANSACTION_APPROVAL_STATUS_UPDATED
tenantId string Unique id of your Fireblocks' workspace
timestamp number Timestamp in milliseconds
data TransactionDetails All the transaction information

VaultAccountAdded

Parameter Type Description
type string VAULT_ACCOUNT_ADDED
tenantId string Unique id of your Fireblocks' workspace
timestamp number Timestamp in milliseconds
data VaultAccount Vault Account details

VaultAccountAssetAdded

Parameter Type Description
type string VAULT_ACCOUNT_ASSET_ADDED
tenantId string Unique id of your Fireblocks' workspace
timestamp number Timestamp in milliseconds
data AssetAddedData Vault-Account-Asset details

AssetAddedData

Parameter Type Description
accountId string The ID of the vault account under which the wallet was added
tenantId string Unique id of your Fireblocks' workspace
accountName string The name of the vault account under which the wallet was added
assetId string Wallet's asset

InternalWalletAssetAdded

Parameter Type Description
type string INTERNAL_WALLET_ASSET_ADDED
tenantId string Unique id of your Fireblocks' workspace
timestamp number Timestamp in milliseconds
data WalletAssetWebhook Internal wallet details

ExternalWalletAssetAdded

Parameter Type Description
type string EXTERNAL_WALLET_ASSET_ADDED
tenantId string Unique id of your Fireblocks' workspace
timestamp number Timestamp in milliseconds
data WalletAssetWebhook External wallet details

ExchangeAccountAdded

Parameter Type Description
type string EXCHANGE_ACCOUNT_ADDED
tenantId string Unique id of your Fireblocks' workspace
timestamp number Timestamp in milliseconds
data ThirdPartyWebhook Exchange accounts details

FiatAccountAdded

Parameter Type Description
type string FIAT_ACCOUNT_ADDED
tenantId string Unique id of your Fireblocks' workspace
timestamp number Timestamp in milliseconds
data ThirdPartyWebhook Fiat account details

NetworkConnectionAdded

Parameter Type Description
type string NETWORK_CONNECTION_ADDED
tenantId string Unique id of your Fireblocks' workspace
timestamp number Timestamp in milliseconds
data NetworkConnection Network connection details

Data Objects

WalletAssetWebhook

Parameter Type Description
assetId string The wallet's asset
id string The ID of the wallet
name string The name of wallet
address string The address of the wallet
tag string Destination tag (for XRP, used as memo for EOS/XLM and as Bank Transfer Description for Signet/SEN) of the wallet
activationTime string The time the wallet will be activated in case wallets activation posponed according to workspace definition

ThirdPartyWebhook

Parameter Type Description
id string Id of the thirdparty account on the Fireblocks platform
subType string Subtype of the third party, ie. exchange or fiat name
name string Account name

ReSend

Resend all failed webhook notifications


result = fireblocks.resend_webhooks()


const result = await fireblocks.resendWebhooks();

The above command returns webhookCount which is the number of resent webhok notifications.

Resends all the failed webhooks pending the backoff retry mechanism to be resent.

HTTP Request

POST /v1/webhooks/resend

Response

Returns 200 on success.

Transfer Statuses

TransactionStatus

TransactionSubStatus

NetworkStatus

TransferTicketStatus

TransferTicketTermStatus

Changelog

17-11-2021

   

22-10-2021

   

17-10-2021

   

08-10-2021

   

07-10-2021

   

6-10-2021 - Breaking Change!!

   

06-09-2021

   

11-08-2021

   

10-08-2021 - Breaking Change!!

   

11-07-2021

31-05-2021

18-05-2021

11-05-2021