Fireblocks Integration for Vault, Wallet & Transaction Syncing

​

How It Works

1. Secure Setup - Corsa generates an RSA key pair and a certificate signing request (CSR). You upload the CSR in Fireblocks and provide the resulting API User ID back to Corsa.
2. Scheduled Sync - Corsa periodically reads Fireblocks vault accounts, deposit addresses, supported assets, and transactions.
3. Real-Time Webhooks - Fireblocks sends configured webhook events to Corsa for new transactions, status changes, new vault accounts, and new vault assets.
4. Entity Mapping - Corsa maps Fireblocks data into corporate and individual clients, blockchain wallets, deposits, withdrawals, vault-to-vault transfers, and pre-created trade transaction legs.
5. Ongoing Updates - Repeated syncs and webhook events upsert existing Corsa records by stable reference IDs, reducing duplicates.

​

What Gets Synced

​

Vault Accounts and Clients

1. Vault-level mapping via customerRefId — If the Fireblocks vault account has a customerRefId, Corsa looks up a client by that value (treated as a Corsa client id or referenceId). This is the most precise mapping and takes precedence over all other methods.
2. Workspace-level mapping via fireblocksWorkspaceId — If the vault has no customerRefId, Corsa checks whether any Corsa client has integrations.fireblocksWorkspaceId set to the current Fireblocks workspace ID. When found, all unmapped vaults in that workspace are associated with that client. This is the recommended approach for multi-workspace setups where all vaults in a workspace belong to the same client.
3. No mapping — If neither method resolves a client, the vault is skipped for wallet and transaction sync. Transactions from that vault can still update pre-created Corsa transactions when externalTxId is used (see Pre-Created Transaction Linking).

​

Deposit Addresses and Wallets

• Wallets are keyed by the Fireblocks vault account, asset, and address.
• Wallets are associated with the owning client.
• If a Fireblocks address has its own customerRefId, that value takes precedence over the vault-level client association.
• Corsa resolves the blockchain network from the Fireblocks asset ID when possible.
• Corsa imports vault deposit addresses. Fireblocks address-book wallets are not imported as standalone wallet records.

​

Transactions

• Incoming vault transactions become Corsa deposits.
• Outgoing vault transactions become Corsa withdrawals.
• Vault-to-vault transactions between two mapped vaults become Corsa transfers.
• If a vault-to-vault transaction cannot be linked to Corsa clients on both sides, Corsa skips transfer creation for that transaction.
• Fireblocks transaction customerRefId, when present, takes precedence over the vault-level client for transaction association.
• Fireblocks status, sub-status, operation, note, transaction ID, and externalTxId are preserved as transaction metadata.
• Fireblocks txHash is stored on the Corsa transaction when present.
• Corsa does not create new trade operations from Fireblocks transactions. Trade transaction legs are updated only when you pre-create them in Corsa and set Fireblocks externalTxId.

​

Workspace-Level Client Mapping

​

Finding your Fireblocks Workspace ID

1. Open the Fireblocks Console.
2. Go to Settings → General.
3. Locate the Workspace ID field. It is a UUID such as a1b2c3d4-e5f6-7890-abcd-ef1234567890.
4. Copy the value.

​

Setting the workspace ID on a Corsa client

curl -X PUT https://api.corsa.finance/v1/clients/corporates/{clientId} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "integrations": {
      "fireblocksWorkspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

curl -X PUT https://api.corsa.finance/v1/clients/individuals/{clientId} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "integrations": {
      "fireblocksWorkspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

​

Behavior once set

• All vault accounts in that workspace without customerRefId are automatically mapped to this client for wallet and transaction sync.
• Vaults that do have customerRefId continue to map to their specific client — customerRefId always takes precedence.
• Each workspace ID is unique across your Corsa platform — it cannot be assigned to more than one client (corporate or individual).

​

Removing or reassigning the mapping

curl -X PUT https://api.corsa.finance/v1/clients/corporates/{clientId} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "integrations": {
      "fireblocksWorkspaceId": null
    }
  }'

​

Multi-Workspace Support

• Vault accounts, wallets, and transactions from each workspace are processed separately.
• Credentials and webhook signatures are resolved per workspace.
• Workspace-level client mapping (fireblocksWorkspaceId) applies only within the workspace it is configured for — a client mapped to workspace A does not receive vault data from workspace B.

​

Pre-Created Transaction Linking

• Corsa finds the matching deposit transaction, withdrawal transaction, or trade transaction leg.
• Corsa updates Fireblocks details such as txHash, metadata, and status.
• If the match is a trade transaction leg, Corsa updates the leg and recalculates the parent trade status.
• Corsa does not overwrite customer-supplied fields such as amount, currency, source, destination, or trade side.
• If there is no matching Corsa transaction and the Fireblocks vault is not mapped to a client, the event is skipped.

​

Trade Leg Updates

​

Sync Modes

​

Real-Time Webhooks

​

Status Mapping

​

API Access

​

Setup Guide

​

Prerequisites

• A Fireblocks workspace with permission to create API users and configure webhooks.
• Owner access to the Corsa application.
• Corsa clients created ahead of time if you want Fireblocks customerRefId values or workspace-level mapping to link vault data to specific clients.

​

Step 1 - Create the Integration in Corsa

1. Log in to Corsa.
2. Go to Developers Hub → Integrations.
3. Click Configure on the Fireblocks card.
4. Configure the Polling Interval. The default is 10 minutes.
5. Create the integration.

• A Certificate Signing Request (CSR) for Fireblocks API authentication
• A Webhook URL for Fireblocks events
• The list of webhook events to enable

​

Step 2 - Create an API User in Fireblocks

1. Open the Fireblocks Console.
2. Go to Settings → API Users.
3. Create a new API user.
4. Upload the CSR file generated by Corsa.
5. Grant the API user read access for vault accounts, vault assets and addresses, supported assets, and transactions.
6. Copy the API User ID that Fireblocks provides.

​

Step 3 - Configure Webhooks in Fireblocks

1. In the Fireblocks Console, go to Settings → Webhooks.
2. Add the webhook URL generated by Corsa.
3. Enable transaction.created, transaction.status.updated, vault_account.created, and vault_account.asset.added.
4. Save the webhook configuration.

​

Step 4 - Complete Setup in Corsa

1. Return to the Fireblocks integration setup in Corsa.
2. Enter the Fireblocks API User ID.
3. Save the integration.

​

Step 5 - Map Vaults to Clients

​

Security

• CSR-based API authentication ensures the Fireblocks private key is generated and stored by Corsa.
• Webhook signatures are cryptographically verified on every incoming event.
• API credentials are securely stored and encrypted.
• All communication uses HTTPS/TLS.

​

Troubleshooting