The Fireblocks connector polls a Fireblocks workspace and surfaces its vault accounts, balances, and transactions to the Connectivity service as read-only streams.
Prerequisites#
You need a Fireblocks account with an API key dedicated to Formance, carrying the least permissions required for the capabilities you plan to use.
Make sure to create an API key dedicated to Formance. Doing so will improve your auditability and security and will allow you to revoke access to Formance at any time if needed.
Installation#
curl -X POST $FORMANCE_API_URL/api/payments/connectors/fireblocks \
-H "Content-Type: application/json" \
-d @config.jsonWith config.json containing:
{
"apiKey": "string",
"endpoint": "string",
"name": "string",
"pollingPeriod": "30m",
"privateKey": "string"
}Configuration fields#
| Field | Required | Default | Description |
|---|---|---|---|
apiKey | yes | — | API key created from the Fireblocks workspace. |
endpoint | yes | — | Base URL for the Fireblocks API. The value depends on your workspace environment (see Endpoints below). |
name | yes | — | A unique name for this connector instance. |
pollingPeriod | no | 30m | How often the connector polls Fireblocks for new data. |
privateKey | yes | — | Fireblocks API secret key. Used to sign the JWT for the Authorization Bearer header. Must be a single-line string with literal \n characters. |
You can convert a PEM file to the expected single-line format with:
cat fireblocks_private.pem | awk '{printf "%s\\n", $0}'Endpoints#
| Environment | URL |
|---|---|
| US Sandbox | https://sandbox-api.fireblocks.io |
| US Mainnet/Testnet | https://api.fireblocks.io |
| EU Mainnet/Testnet | https://eu-api.fireblocks.io |
| EU2 Mainnet/Testnet | https://eu2-api.fireblocks.io |
Capabilities#
The Fireblocks connector is read-only as of Payments v3.2 — it does not initiate payouts, transfers, or webhook deliveries. The supported capabilities are:
- FetchAccounts — sync vault accounts from Fireblocks.
- FetchBalances — retrieve per-asset balances for each vault.
- FetchPayments — import transactions, including withdrawals, transfers, staking/unstaking, and minting/burning.
Asset model#
The canonical asset string emitted by the connector is derived from Fireblocks' displaySymbol, sanitized where needed, and suffixed with /precision — for example, USDT/6 and ETH/18. The underlying Fireblocks legacyId (USDT_ERC20, ETH_TEST5, …) is preserved per payment under com.fireblocks.spec/legacy_id metadata.
Multi-chain aggregation#
Same-symbol holdings across chains in a single vault collapse into one balance. A vault holding both USDT_ERC20 and USDT_TRX produces a single USDT/6 balance row with the summed amount. Per-chain identity remains observable at the payment level via the com.fireblocks.spec/blockchain_id, com.fireblocks.spec/legacy_id, and com.fireblocks.spec/contract_address metadata fields, so a USDT/6 payment from one chain stays distinct from a USDT/6 payment on another.
Testnet segregation#
Assets that live on a testnet blockchain (per Fireblocks' Blockchain.onchain.test flag) carry a _TEST suffix on the canonical asset string and are tagged with com.fireblocks.spec/testnet=true. Examples: ETH_TEST/18, SOL_TEST/9, BTC_TEST/8. Mainnet and testnet holdings of the same symbol never collide downstream.
Asset classes the connector skips#
The connector ingests NATIVE, FT, and FIAT asset classes only. Assets whose assetClass is NFT, SFT, or VIRTUAL, or that Fireblocks has marked deprecated, do not appear in the Accounts, Balances, or Payments streams.
Sanitization rules#
When displaySymbol cannot be used verbatim, the connector applies these rules to produce a Ledger-compatible asset string:
- Lowercase characters are uppercased (
xDAI→XDAI). - A digit-prefix is stripped until the first letter (
1INCH→INCH). - Characters outside
[A-Z0-9]are dropped. - The base is capped at 17 characters; testnet assets additionally carry the
_TESTsuffix.
First sync
The connector pins after=1 on the initial poll, bypassing Fireblocks' default 90-day window so the full transaction history is backfilled. A fresh install against a workspace with a long transaction history may take several poll cycles to surface every payment, with new rows appearing as each cycle completes.
Metadata keys#
The connector stamps Fireblocks-specific context under the com.fireblocks.spec/ namespace so that the chain, contract, and classification details remain visible after the asset string has been canonicalized.
Account metadata#
Emitted on PSPAccount.metadata only when the corresponding Fireblocks field is set or true.
| Key | Source |
|---|---|
com.fireblocks.spec/customer_ref_id | VaultAccount.customerRefId |
com.fireblocks.spec/hidden_on_ui | VaultAccount.hiddenOnUI |
com.fireblocks.spec/auto_fuel | VaultAccount.autoFuel |
Payment metadata#
Every payment carries the cached asset metadata (the first block below) plus any transaction-level fields that Fireblocks populated (the second block).
| Key | Source |
|---|---|
com.fireblocks.spec/legacy_id | Asset.legacyId |
com.fireblocks.spec/asset_uuid | Asset.id |
com.fireblocks.spec/display_name | Asset.displayName |
com.fireblocks.spec/display_symbol | Asset.displaySymbol |
com.fireblocks.spec/blockchain_id | Asset.blockchainId |
com.fireblocks.spec/asset_class | Asset.assetClass (NATIVE, FT, FIAT) |
com.fireblocks.spec/contract_address | Asset.onchain.address |
com.fireblocks.spec/token_standard | Asset.onchain.standards (comma-joined) |
com.fireblocks.spec/verified | Asset.metadata.verified (only when true) |
com.fireblocks.spec/features | Asset.metadata.features (comma-joined) |
com.fireblocks.spec/testnet | derived from Blockchain.onchain.test (only when true) |
| Key | Source |
|---|---|
com.fireblocks.spec/tx_hash | Transaction.txHash |
com.fireblocks.spec/network_fee | Transaction.feeInfo.networkFee |
com.fireblocks.spec/note | Transaction.note |
com.fireblocks.spec/sub_status | Transaction.subStatus |
com.fireblocks.spec/destination_ids | Transaction.destinations[].id (multi-destination transactions only) |
The full Fireblocks Transaction body is preserved verbatim on /v3/payments/{paymentID}.adjustments[].raw. The payments list endpoint does not inline adjustments, so retrieve the payment by ID to access the raw payload. Vault payloads are available verbatim on PSPAccount.raw and are inlined on both the list and detail account endpoints.
Rate limits#
Rate limits are per endpoint, per transaction, per minute and depend on your contract with Fireblocks. See the Fireblocks rate limiting documentation for details.