Fireblocks connects businesses across the crypto world as the digital asset infrastructure for over 1,600 of the leading trading desks, hedge funds, brokerages, custodians, 3rd parties, and banks. To meet the demand of third-party services that want to access the liquidity of institutional investors and traders, Fireblocks is opening our platform for third-party solutions to quickly integrate into the Fireblocks platform. Reach out to us for a partnership agreement and add a Connector to have your product integrated.
- Enhance your service's visibility and liquidity by immediately gaining access to 1000s of workspaces.
- Fireblocks customers transact 20x more with 3rd parties supported on Fireblocks vs. unsupported 3rd parties
- Deliver a better experience to your customers who use Fireblocks with greater control of how the Fireblocks platform interacts with your 3rd party.
- Control rate limits and response codes
- Manage the supported assets
- Optimize the platform load for requests from Fireblocks
Fireblocks customers use the Fireblocks web-based console to connect their third-party accounts such as crypto 3rd partyie. This requires generating an API Key and an API Secret from their 3rd party portals, logging into their Fireblocks Console, adding an 3rd party account, selecting the 3rd party by a name and a logo, and then entering their account API Key, API Secret, and login details.
Once the third-party account is connected, Fireblocks customers can use the Fireblocks Console and API to:
- View their 3rd party account balances for their main, sub, and various trading accounts
- Withdraw and deposit funds between their connected 3rd party accounts, their Fireblocks Vault, and counterparties
- Track the status of their withdrawals and deposits
- View and audit their transaction history
Contact your Fireblocks Sales Rep to list your 3rd party in the Fireblocks ecosystem. You will need to sign a licensing agreement for listing your 3rd party. Please note that an 3rd party listing license agreement is separate from a self-custody license agreement, and neither agreement is required to sign the other. Once signed, you will receive a test environment to connect and begin integrating your pending 3rd party integration.
Begin configuring inbound connections for the API endpoints described below. Fireblocks initiates calls to each of these endpoints under your base URL whenever a Fireblocks customer accesses your 3rd party using the Fireblocks integration. Once your contract is signed, the Fireblocks technical team will reach out to you to gather your 3rd party registration settings (see below).
Fireblocks starts each 3rd party integration with a short beta program. At a minimum, the beta participant will be yourself. Optionally, you may engage with your clients who already use Fireblocks for trading and self-custody to provide feedback on the beta program. Once the Fireblocks team determines the beta is successful, your 3rd party is made available to all Fireblocks customers, alongside mutual marketing activities to promote the launch.
Once your license agreement for listing your 3rd party with Fireblocks is signed, the Fireblocks technical team will request the following 3rd party registration settings:
- Display name: i.e. “My Exchange” or “My Exchange Sandbox”
- Icon: a 32x32 .svg file
- Step-by-step guide for generating an API Key from your 3rd party platform.
- A public link to your knowledge base is preferred (A sharable document or PDF is also acceptable).
- Base URL for your API endpoints: i.e. https://my-service.com/fireblocks
- Version: The Fireblocks Network Link major version number. Our current and only major version is 1.
- What is your main account's fundable type? (The account type where Fireblocks users can deposit and withdraw funds)
- Is 3rd party a sandbox environment: true or false
- Connection supports withdrawals from the 3rd party: true or false
- Connection supports deposits to the 3rd party: true or false
- Connection supports sub-accounts: true or false
- Connection supports sub-account to sub-account transfers: true or false
- What is your sub account's main fundable type? By default it is equal to the main account's fundable type.
- Does transferring assets to the 3rd party account require manually generating a deposit address on the 3rd party's portal?: true or false
- Upon withdrawals, does your 3rd party require the "address" & "tag" field to be masked?: valid values are NONE, SHA512, SHA3_256, SHA256. NONE is the default.
- Select your authentication preferences:
- HMAC:
- Request encoding format: valid values are PLAIN, BASE64, HEXSTR, BASE58, BASE32
- Request signing format: valid values are: SHA512, SHA3_256, SHA256
- Signature encoding result: valid values are PLAIN, BASE64, HEXSTR, BASE58, BASE32
- RSA:
- Request encoding format: valid values are PLAIN, BASE64, HEXSTR, BASE58, BASE32
- Request signing format: valid values are: SHA512, SHA3_256, SHA256
- Signature encoding result: valid values are PLAIN, BASE64, HEXSTR, BASE58, BASE32
- ECDSA:
- Request encoding format: valid values are PLAIN, BASE64, HEXSTR, BASE58, BASE32
- Request signing format: valid values are: SHA256
- Signature encoding result: valid values are PLAIN, BASE64, HEXSTR, BASE58, BASE32
All REST requests will contain the following headers:
*X-FBAPI-KEY* The API key as a string.
*X-FBAPI-SIGNATURE* The payload signature output.
*X-FBAPI-TIMESTAMP* A timestamp of the request (in milliseconds)
*X-FBAPI-NONCE* A unique reference to the request (Random)
The X-FBAPI-TIMESTAMP header is the number of milliseconds since Unix Epoch in UTC. e.g. 1547015186532
The difference between the timestamp and the 3rd party time must be less than X seconds.
The amount of seconds (=X) is up to the 3rd party to decide - recommended to be a reasonable amount.
It's expected that the request on the 3rd party's end will be considered expired and rejected otherwise.
[Authentication scheme is configurable: HMAC, RSA, ECDSA]
The API-KEY and SECRET are necessary, and are generated and provided by the 3rd party.
Signature procedure:
-
Create a prehash string {timestamp+nonce+method+endpoint+body}.
-
Apply an encoding onto the prehash string (Pre-encoding is configurable: PLAIN, BASE64, HEXSTR, BASE58, BASE32)
[The request body is a JSON string and need to be the same with the parameters passed by the API]
-
Use SECRET to sign the string with HMAC (Internal hash function is configurable: SHA512, SHA3_256, SHA256)
-
Apply an additional encoding onto the signature result (Post-encoding is configurable: PLAIN, BASE64, HEXSTR, BASE58, BASE32)
Supported RSA Parameters [PKCS1v15]
The API-KEY and SECRET are necessary, and are generated and provided by the 3rd party.
SECRET is defined to be the Private RSA PEM.
Signature procedure on Fireblocks's end:
-
Create a prehash string {timestamp+nonce+method+endpoint+body}.
-
Apply an encoding onto the prehash string (Pre-encoding is configurable: PLAIN, BASE64, HEXSTR, BASE58, BASE32)
[The request body is a JSON string and need to be the same with the parameters passed by the API]
-
Use SECRET to sign the string with RSA (Internal hash function is configurable: SHA512, SHA3_256, SHA256)
-
Apply an additional encoding onto the signature result (Post-encoding is configurable: PLAIN, BASE64, HEXSTR, BASE58, BASE32)
Supported ECDSA Parameters [prime256v1/secp256k1]
The API-KEY and SECRET are necessary, and are generated and provided by the 3rd party.
SECRET is defined to be the Private ECDSA PEM. ECDSA result signature has an ASN1.DER format.
Signature procedure on Fireblocks's end:
-
Create a prehash string {timestamp+nonce+method+endpoint+body}.
-
Apply an encoding onto the prehash string (Pre-encoding is configurable: PLAIN, BASE64, HEXSTR, BASE58, BASE32)
[The request body is a JSON string and need to be the same with the parameters passed by the API]
-
Use SECRET to sign the string with ECDSA (Internal hash function is not configurable and is set to: SHA256)
-
Apply an additional encoding onto the signature result (Post-encoding is configurable: PLAIN, BASE64, HEXSTR, BASE58, BASE32)
- The timestamp in the signature payload is consistent with the X-FBAPI-TIMESTAMP field in the request header.
- The body to be signed is consistent with the content of the request body.
- The method is always UPPER CASE.
- For GET requests, the endpoint in the signature payload contains the query string. e.g. /v1/depositAddress?coinSymbol=ETH&...
- The endpoint in the signature payload is always in a path-relative format.
- The endpoint in the signature payload could contain more paths, it's configurable. e.g. (DEFAULT) /v1/depositAddress, /fireblocks/v1/depositAddress...
- The body is "" if there is no request body (for GET requests).
Upon failures, the expected format of the error is as follows:
{"error": "Missing request header params", "errorCode": 400000}
"error" must be a string and is required.
"errorCode" must either be a number or null.
| Missing request header params | 400000 |
| Nonce sent was invalid | 400001 |
| Timestamp sent was invalid | 400002 |
| Signature sent was invalid | 400003 |
| Insufficient permissions for this API key | 400004 |
| Insufficient funds to carry out this operation | 400005 |
| Insufficient fee to carry out this operation | 400006 |
| Unsupported account type for this 3rd party | 400007 |
| Unsupported operation for this 3rd party | 400008 |
| Asset not supported on this 3rd party | 400009 |
| One of the parameters sent in the body or query is invalid | 400010 |
| Bad address format sent | 400011 |
| Balance amount is too small | 400012 |
| This 3rd party needs manual deposit address generation | 400013 |
| The 3rd party rejected this operation | 400014 |
| Withdraw was cancelled or failed on the 3rd party | 400015 |
| Address wasn't whitelisted | 400016 |
| IP wasn't whitelisted | 400017 |
| Account not found | 400018 |
| Withdrawals are limited by the 3rd party. Please try again in a bit. | 400019 |
| 3rd party has denied the request - a settlement is required! | 400020 |
Note that not all error codes need to be in use!
All notable changes to this project will be documented in this file. Dates are displayed in UTC.
07 Dec 2023
- Added new account types - MARGIN_CROSS, USDT_FUTURES, COIN_FUTURES.
02 Dec 2023
- Added an optional direction param for the transaction history endpoint.
06 August 2023
- Supporting new networks Chiliz 2.0 and Flare.
17 July 2023
- Added isSettlementTx as a flag for the withdraw endpoint, for third party services that support off-exchange.
16 July 2023
- Withdrawal destination tag will be masked the same way the address is, if configured.
10 May 2023
- Changed the isGross and isSubTransfer documented type, from boolean to string.
13 March 2023
- Added ECDSA support in addition to HMAC/RSA support.
26 Feb 2023
- Supporting EthereumPoW and Luna Classic networks on Mainnet.
2 Feb 2023
- Added more details the RSA support.
- Added more details on the signature payload.
- Renamed to "Fireblocks Connector for Third Party Services"
29 Jan 2023
- Added RSA support in addition to HMAC support
- Withdrawal destination address can now become masked with a hash value, if configured.
29 Dec 2022
- Added credit balance instead of the borrow balance on /accounts endpoint
- Added new settlement error
- Can configure a different fundable account type for sub accounts
- Gas fees description added for isGross
18 Nov 2022
- Moved to Fireblocks Github repo
- Rename to Fireblocks Connector for Exchanges