Fireblocks is the digital asset infrastructure for 1,000s of the leading trading desks, hedge funds, broke rages, custodians, and banks. Through the Fireblocks Console, users connect and trade on over 30 exchanges. As part of an important inti ative, making sure that the end user still has complete control over his own asset Fireblocks offers the Off Exchange solution. This way , the end user can enjoy the various benefits of the exchange while avoiding the risk of a centralized malfunction.

Benefits

• Complete end user control.
• Provide a trustable relationship, where the customer safely continues his work with the exchange.
• Control rate limits and response codes
• Manage the supported assets
• Optimize the platform load for requests from Fireblocks

Prerequisites

To implement the collateral accounts functionality, an active Fireblocks/Exchange integration is needed. It is recommended to implement the Fireblocks Network Link to enable Fireblocks users to link exchange accounts to their Fireblocks’ workspaces.

Background

The purpose of the Fireblocks collateral account is to enable a middle ground for Traders and Exchanges where Traders assets are not stored in Exchange’s private ledger, yet the exchange get the comfort to lend against the collateral account assets, by having the collateral assets locked by Fireblocks, preventing the Trader from removing collateral assets without getting Exchange confirmation first.

Account structure and account linking (API key replace)

Fireblocks enables any user to link exchange accounts to their workspace. Once an exchange account is linked to Fireblocks, the user can at least view the account balance, and deposit and withdraw assets directly from the Fireblocks workspace.

For the collateral assets, Fireblocks will open a dedicated Vault Account which will be called Collateral Vault Account (CVA). Any assets added to the CVA will be locked by the Fireblocks Policy and removing collateral assets from the CVA will require exchange’s confirmation.

Fireblocks users will be able to add collateral for main exchange accounts only (MEA).

There is a 1:1 relation between a CVA and a main exchange account (MEA).

The expected flow is for Traders to add collateral for a MEA, gain credit on their MEA balance, and then allocate assets to the various MEA child-accounts.

Exchanges need to track collateralId to an internal accountId and in case of an API key replacement, to respond to CVA initiation with the existing collateralId.

For settlements, Traders would need to transfer assets up to the MEA as settlements will be executed on the CVA and MEA balances only.

Deposit/Withdraw Vs Remove/Add

The collateral functionality should apply to any main exchange account of a customer that has enabled this functionality. Meaning, once a customer is eligible and onboarded, all the existing main exchange accounts of this customer should be enabled for gaining credit against CVA assets, while maintaining the usual deposit and withdrawal functionality.

We use the terms ‘add collateral’ and ‘remove collateral’ to distinguish between the CVA and the MEA. For the MEA, we keep referring with the usual deposit and withdraw terminology.

Please be aware that Fireblocks expect the deposits and withdrawals to and from the MEA to remain active and available for CVA-linked MEAs.

If a withdrawal from a MEA is denied due to outstanding MEA credit or customer-level credit, the exchange needs to respond with a ‘settlement is required’ note/status.

Post Address and Addresses list

As mentioned, FB will send a POST request each time a collateral is added via the FB systems. The request will include the address/es to which the collateral assets are deposited. The Exchange needs to identify whether the address/es are new and if so then to add the new addresses to the CVA addresses list. FB will not supply TxID for adding collateral, as the Exchange is expected to monitor the on-chain transactions and to credit once completed, based on the exchange confirmation threshold and risk management engine.

Balance types

Once a CVA is created for a MEA, Fireblocks will start presenting Traders with 3 types of exchange balance.

1. MEA Total/Available balance.
   • This is the usual balance that is presented to non-CVA users as well.
2. MEA credit balance.
   • This is a new type of balance, supplied to Fireblocks by the Exchange, and reflects the outstanding credit the MEA gained from the Exchange treasury in accordance with the locked CVA assets.
   • The credit balance does not have to be equal to the CVA balance.
     • For example, if Trader adds 100 BTC as collateral but Exchange decides to credit the MEA with 40 BTC only, due to risk management considerations and Trader cross-accounts credit utilization, then the credit balance would be 40 BTC while 100 BTC are stored in the CVA.
       • In this case, if Trader asks to remove the 60 BTC surplus from the CVA, Exchange should confirm this collateral removal.
3. MEA collateral balance.
   • This is in fact the CVA balance which is being managed by Fiireblocks.

Capabilities and features

Initiation - we send Collateral ID and we want to get back a success with Collateral ID. If the API Key we use is of an account that already has a collateral ID, we want the success message to contain the existing collateral ID and we will not use the new one.

Network fees

Settlement transactions are on-chain transactions. Exchange should estimate future fees once crediting a Trader account relying on the CVA locked assets.

Exchange A may choose to credit 1:1 (e.g 1 BTC credit for each 1 BTC in CVA), but to ask for settlements earlier than Exchange B that chooses to credit 0.8:1 in order to keep aside an amount to cover settlement transactions’ network fees.

Gas

Settlements that involve gas-powered assets transferred from a CVA to an exchange OTA, require the Trader to make sure there’s enough gas.

As a fallback, Exchange can deposit gas to the CVA by querying for the Ethereum address or any other base asset address.

At this time, Fireblocks will not manage gas stations for CVAs.

Collateral ID

The identifier of the CVA is called ‘collateral ID’ and is represented as a series of 3 uuid4 formats separated with a . delimiter.

Supported Assets

Fireblocks keeps a record of each exchange supported assets. On each deposit into the CVA, Fireblocks sends a POST call to the exchange with the address to which the asset is being deposited, the name of the asset and network as the exchange defined them, and the unique fireblocksAssetId which the exchange needs to track in order to communicate with Fireblocks about this asset.

Fireblocks will not allow users to add unsupported assets as collateral. A caveat to that rule is that a user may transfer funds to a CVA not via the Fireblocks UI/API. In that case, the exchange would not get a POST ‘address’, and may ignore that deposit, not credit against it, and confirm its removal once asked for.

Assets that Fireblocks do not support cannot be included in settlements. If a non-supported asset is at the MEA and needs to settle, the exchange wouldn't be able to include it in the settlement as there isn’t any Fireblocks Asset Id for assets that Fireblocks do not support.

Settlements

As settlement transactions are on-chain transactions, frequency based settlements are not recommended, to minimize network fees. Instead, the best practice for exchanges to trigger settlements would be based on the value difference between the CVA assets and the total exchange account value (including unrealised P&L). Traders may trigger settlements after spot trading where the value difference may be minimal, but for the exchange-side settlement-logic, risk appetite for a specific

Auto-sign settlement transactions

The following description is for the available auto-sign mechanism for settlement transactions that customers do not respond to.

Exchanges can choose to require some or all customers to create an API-based user in the Collaterals Workspace, for the exchange to run on an exchange owned and operated machine. This is a user from a Collaterals Signer role, which is limited, cannot fetch balances, cannot initiate transactions, but can sign some settlement transactions as described below.

If a customer does not sign and does not deny settlement transactions during the SLA that was defined by the exchange for the customers to respond to settlement transactions, then at the end of this SLA time, these transactions which the customer did not sign nor deny, will be sent by Fireblocks to the exchange Collaterals Signer user to be automatically signed.

No development is required, only operations of deploying and running a machine for the Collaterals Signer user to be online ready to sign transactions if needed.

Customers can create a Collaterals Signer user after getting a CSR from the exchange.

If customers deny a settlement transaction, the denied transaction will not be sent to the Collaterals Signer for auto-sign.

Forced Settlement

For exchanges that want to prevent continuous ‘deny’ situations with customers, Fireblocks enables the Forced Settlement flow, which like the Auto-sign flow, requires the exchange to run a Collaterals Signer machine.

At the end of the Auto-sign SLA, if customers have denied some or all of the settlement transactions, the exchange can mark the settlement as a Forced Settlement candidate. We strongly recommend the exchange to contact the customer and get to an agreed upon settlement terms, Fireblocks will anyway alert the customer about any settlement that is being marked for enforcement.

Marking a settlement as a ​​Forced Settlement candidate means that all of the non-completed transactions that were part of the settlement ID will be enforced. Per-transaction marking is not supported, but a new settlement can be created if as a result of discussing with the customer, some of the transactions from the original settlement have changed.

The marking is done by sending a PUT request to Fireblocks settlements/force endpoint, and can be done for the last settlement only. A request to mark a settlement ID which is not the last settlement ID created, will be failed. Once a settlement has been marked as a Forced Settlement candidate, no other settlement can be initiated before either the marking is canceled, or the Forced Settlement is completed. Only one settlement can be marked at a given time.

Once a settlement has been marked as a Forced Settlement candidate, Fireblocks stops Off-exchange operations (Add collateral, Remove collateral, GET/POST Settlement request from the customer).

Canceling the marking is done by sending a DEL request to Fireblocks settlements/force endpoint.

An Enforcement SLA should be set by the exchange and communicated to customers.

During the time between marking a settlement and forcing it at the end of the SLA, the exchange can get information about a marked settlement by sending a GET request to Fireblocks settlements/force endpoint.

At the end of the Enforcement SLA, the exchange can force all the non-completed transactions from the original settlement by sending a POST request to Fireblocks settlements/force endpoint. This request starts an asynchronous process. This request will not be answered before the following process ends. Once Fireblocks get the POST Force req, Fireblcoks send a POST request to the exchange on the settlements/force endpoint on the exchange side, with a list of the transactions to be created. If the exchange approves the transactions list, Fireblocks creates a new settlement ID, new transaction IDs, and those are included in the response to the POST request from the exchange that started this asynchronous process.

We will enable exchanges to mark the last settlement ID for up to 7 days since the settlement ID creation.

We will enable exchanges to force a settlement for up to 10 days since the settlement ID creation.

Getting Started to Official Launch

Contact your Fireblocks Sales Rep to list your exchange (partner) in the Fireblocks ecosystem. You will need to sign a licensing agreement for listing your exchange. Please note that an exchange listing license agreement is separate from a self-custody license agreement, and neither agreement is required to sign the other.

Registration

Once your license agreement for listing your exchange with Fireblocks is signed, the Fireblocks technical team will request the following partner registration settings:

1. API certificate upload
2. New partner registration:
   • Partner name that should be displayed
   • Partner Configuration preferences:
     • Support collateral tx monitoring flag - specifies to the exchange the collateral transaction id when adding funds to the collateral account, to allow polling "add collateral" transactions (using the EX->FB endpoint get transaction details). Possible values: true or false.
     • Support multiple environments flag - supplies an environment description when a partner account eligibility is verified. (using the EX->FB endpoint get transaction details) Possible values: true or false.
     • Include recovery account ID in POST v1/collateral/address flag - supplies the recovery account id for the address.
     • Support signatures from Fireblocks - If the partner wants to include X-OFF-EXCHANGE-TIMESTAMP, X-OFF-EXCHANGE-SIGNATURE and X-OFF-EXCHANGE-NONCE on the requests.
     • Support signatures from the Partner - If the integration will enforce the X-OFF-EXCHANGE-SIGNATURE validity on the responses.

Collateral Signer Creation Automation

To ensure a seamless onboarding process the off-exchange clients, we have developed an automation for creating the Collateral Signer user. This user is created right after the creation of a collateral workspace that will hold the CVAs. The creation process for the Collateral Signer user entails pairing it with a designated co-signer that runs on a Partner’s owned machine. This pairing procedure utilizes a user pairing token, which can be pulled from Fireblocks. Upon completion of the user creation process, Fireblocks will notify the Partner that a Collateral Signer user is ready, and its pairing token can be pulled. Afterwards, the pairing token can be added as a new Collateral Signer user to the Partner’s Collateral Signer machine.

Setup

Deposit

Withdrawal

Settlement

Collateral Signer Automation Flow

Forced Settlement

High-Level Flow Diagram

In-depth - Marking a settlement as a candidate for enforcement

In-depth - Forcing a settlement

Fireblocks to Exchange Notifications

Authentication

Validation for Fireblocks events is done by validating the signature attached in the request header:

Signature procedure on Fireblocks's end for Exchange Notifications:

1. Fireblocks signs the eventbody with a private RSA key using the hash function SHA512.

2. Apply BASE64 encoding onto the signature result.

The Fireblocks server will look for a response to confirm the notification was received. All events should receive an HTTP-200 (OK) response. If no response is received, Fireblocks will resend the request several more times, the retry schedule (in seconds) is 15, 45, 105, 225, 465, 945, 1905, 3825, 7665, and 15345.

Fireblocks Public key

Fireblocks Verify Code Example

Request Structure

All requests will contain the following header:

Fireblocks-Signature The payload signature output:

Fireblocks-Signature: Base64(RSA512(_RSA_PRIVATE_KEY, SHA512(eventBody)))

Fireblocks to Exchange Operations Requests

Authentication

Fireblocks supports the key/secret authentication for outgoing requests as with regular non off-exchange customer requests. In addition, RSA-4096 digital signature scheme will be used for sign and verification for all Fireblocks to Exchange Operations requests/responses. Important note: Authentication is an enhancement in the secure communication between Fireblocks and partners, utilized alongside user authentication for the exchange integration.

Signature procedure on Fireblocks's end:

1. Create a prehash string {timestamp+nonce+method+endpoint+body}. Prehash string is not encoded (using a plain text).
   [The request body is a JSON string and need to be the same with the parameters passed by the API]

2. Fireblocks signs the string with the company's private RSA key using the hash function SHA512.

3. Apply BASE64 encoding onto the signature result.

List of public keys per environment:

• Development Fireblocks RSA Public Key (For integration purposes)
• Production Fireblocks RSA Public Key

Request Structure

All requests will contain the following headers:

X-OFF-EXCHANGE-NONCE A unique reference to the request (Random GUID)

X-OFF-EXCHANGE-TIMESTAMP A timestamp of the request (in milliseconds)

X-OFF-EXCHANGE-SIGNATURE The payload signature output: Using Fireblocks private RSA key on the signature payload: {timestamp+nonce+method+endpoint+body}

Response Structure

X-OFF-EXCHANGE-SIGNATURE The payload signature output: Using partner private RSA key on the signature payload: {timestamp+nonce+method+endpoint+body} NOTE: The timestamp and nonce is the same as the request!

Endpoints

The following are the endpoints that Fireblocks can call against the exchange. Technical documentation can be seen under the endpoint description.

• Verify Collateral Account Eligibility
• Post Partner Deposit Address
• Withdraw
• Settle
• Forced Settlement Confirmation

Exchange to Fireblocks Requests

Authentication

Exchange should a valid signed JWT in every request. The CSR that is correlated to the private key with which the JWTs are signed with, should be delivered to Fireblocks during the integration development process. Fireblocks will supply the exchange with an api key to use in the sub field of the JWT.

Endpoints

The following are the endpoints that the exchange can call against Fireblocks. Technical documentation can be seen under the endpoint description.

• Get the details of a transaction
• Initiate a settlement
• Get settlement transaction ids by settlement id
• Get deposit address from a collateralId by assetId
• Mark a settlement as an enforcement candidate
• Get details about the enforcement candidate
• Cancel the enforcement candidate
• Invoke the enforcement candidate's forced settlement transactions
• Get an updated collateral signers list for a workspace
• Get the list of workspaces containing collateral signers for your service

All notable changes to this project will be documented in this file. Dates are displayed in UTC.

v1.4.2

30 October 2024

• POST /collateral/v1/address - rejectionReason added support

v1.4.1

20 September 2024

• POST /collateral/v1/notify - Restructured the response, removed the "notificationEvent" object.

v1.4

20 June 2024

• Support Collateral Signer Creation Automation
• New endpoint section to support Fireblocks to Exchange Notifications.
• Support queries from the Partners of Collateral Signers and Workspaces lists
• Added support for the new following endpoints:
  • Fireblocks to Exchange Notifications: POST /collateral/v1/notify Receives notifications for pre-defined events in your Fireblocks workspace.
  • Fireblocks to Exchange: POST /collateral/v1/signers/token - Fetch a collateral signer pairing token when a Collateral Signer pairing token is available GET /collateral/v1/signers/data - Get information of existing collateral signers and their current status GET /collateral/v1/workspaces - Get information of the Partner managed workspaces

v1.3

5 March 2024

• Extended authentication mechanism: Added Request/Response structure descriptions for Exchange to Fireblocks endpoints.

v1.2.2

4 March 2024

• POST /collateral/v1/settlement/force: in response, id renamed to forceSettlementId
• POST /collateral/v1/settlement/force: in response, initiator was removed
• POST /collateral/v1/settlement/force: in response, exchangeReply was removed
• POST /collateral/v1/settlement/force: in response, exchangeRequestedTransactions was removed

v1.2.1

22 January 2024

• Update for the following endpoints:

• Fireblocks to Exchange: POST /collateral/v1/address - "recoveryAccountId" field addition.

v1.2

2 January 2024

• Update for the following endpoints:

• Fireblocks to Exchange: POST /collateral/v1/initiate POST /collateral/v1/address

• Added Getting Started to Official Launch and Registration sections.

v1.1

2 November 2023

• Added support for the new following endpoints:

• Fireblocks to Exchange: POST /collateral/v1/settlement/force
• Exchange to Fireblocks: GET /v1/collateral/settlements/force DELETE /v1/collateral/settlements/force PUT /v1/collateral/settlements/force POST /v1/collateral/settlements/force

• Added a guide for the new "Auto-sign settlement transactions" feature.
• Added a guide for the new "Forced Settlement" feature.

v1.0 (DOC fix: 2)

7 July 2023

• GET /v1/collateral/settlements/{settlementId}/transactions: Was missing a collateralId as a query param in the docs.

v1.0 (DOC fix: 1)

25 April 2023

• GET /v1/collateral/address/{assetId}: Was missing a collateralId as a query param in the docs.

v1.0

17 April 2023

• POST /v1/transactions: Renamed to POST /v1/collateral/transactions/{collateralTxId}
• POST /collateral/v1/settlement (Internal): Renamed to POST /v1/collateral/settlements
• GET /v1/collateral/address/{assetId}: Add new EP from Exchange to Fireblocks to get an address of the collateralId.
• POST /v1/collateral/transactions/{collateralTxId}: Redesigned entirely.
• POST /v1/collateral/settlements: Results in 2 arrays of strings instead of 2 arrays of objects.
• All Exchange-to-Fireblocks endpoints: Added instructions on authentication scheme.
• All Exchange-to-Fireblocks endpoints: Added the URL to access the endpoints.

Beta v2.6

13 Feb 2023

• Delimiter of collateralId changed from ':' to '.'

Beta v2.5

16 Jan 2023

• Added Diagrams

Beta v2.4

16 Jan 2023

• Added Guide

Beta v2.3

05 Jan 2023

• POST /collateral/v1/initiate: status field is now a boolean and not a string - indicating success and failure.
• POST /collateral/v1/initiate: collateralId field in the response is a mandatory field in case of status = true, added documentation.

Beta v2.2.2

26 Dec 2022

• POST /collateral/v1/withdraw: transactionId renamed to collateralTransactionId

Beta v2.2.1

25 Dec 2022

• POST /collateral/v1/initiate: approved renamed to status was forgotten, fixed
• POST /collateral/v1/withdraw: fee isn't required for to_collateral, removed requirement
• POST /collateral/v1/withdraw, GET & POST /collateral/v1/settlement: Changed "amount" and "fee" types from number to string.

Beta v2.2

18 Dec 2022

• POST /collateral/v1/initiate: approved renamed to status, contains an enum of options: APPROVED, DENIED, REPLACED.
• POST /collateral/v1/initiate: If status is REPLACED, a new field of collateralId to set on the response.

Beta v2.1

18 Dec 2022

• POST /collateral/v1/settlement: Fixed typo on both to_collateral and to_exchange, they are now arrays of objects instead of just objects.
• GET /collateral/v1/settlement: Fixed typo on both to_collateral and to_exchange, they are now arrays of objects instead of just objects.
• POST /collateral/v1/settlement: sourceAddress field can be null for to_collateral.
• GET /collateral/v1/settlement: fireblocksStatus field renamed to status - field should show the status on the exchange's side.
• POST /collateral/v1/address: asset field renamed to assets - assets is now an array of asset.
• POST /collateral/v1/initiate: Made description more readable.
• POST /collateral/v1/withdraw: transactionId is now a required field.
• POST /collateral/v1/withdraw: Added two new fields sent by Fireblocks - destinationAddress and destinationTag.

Beta v2.0.1

18 Dec 2022

• Supporting failureReason to failed requests.