Stacks blockchain integration via Raw Signing

To request activation of this feature, contact your Customer Success Manager. Raw Signing is classified as a premium feature and may incur an additional platform fee if enabled.

Raw Signing can introduce potential security vulnerabilities. You must follow all Fireblocks security guidelines and best practices when using Raw Signing to minimize associated risks.

Learn more about Fireblocks Raw Signing. For detailed information or assistance, contact the Fireblocks team at any time.

To submit Stacks transactions to the blockchain, transactions must be structured and signed according to network requirements. The SDK and desktop application handle transaction generation and submit them to your Fireblocks workspace for signing.

All Stacks transactions use the Raw Signing operation. Your workspace must have a dedicated Policy rule in place for Raw Signing to ensure the signing process can proceed.

Raw Signing Policy rule

• All Raw Signing transactions are blocked by default. You must create Policy rules to explicitly allow the Raw transaction type.
• Specify who can initiate and who can approve Raw transactions. Best practice is to require a two-tier setup (initiator and a human approver) or use an API user plus a human validator. Avoid initiator rules with Any as the initiator when possible.
• Limit rules to only the source vault accounts, and ideally the specific assets and derivation paths needed for your workflow.
• Raw Signing rules do not support amount caps or destination controls. This is a significant risk compared to normal transfer and contract call rules.
• Scope Raw Signing rules as narrowly as possible, and make them temporary where the need is one-off. Remove or update rules immediately after use.
• Always set up multi-approver or designated signer flows for additional oversight.
• Avoid using Any vault or Any user unless necessary — more granular rules are more secure.
• Ensure all users understand the risks. Raw Signing can bypass most standard controls and is equivalent to signing a blank check.
• Consider using an API Co-signer with a Callback Handler for programmatic validation and additional business logic.

To get started with the SDK, clone our public repository.

The repository's README.md file contains all setup and deployment instructions, as well as TypeDoc documentation. Follow those steps to complete your local or Docker-based environment.

The Fireblocks x Stacks desktop application provides a full-featured interface for managing Stacks operations. Designed for users who prefer not to work with code, it offers secure local access to your Fireblocks vaults and transaction signing workflows via Raw Signing. It includes biometric authentication, STX and custom token transfers, STX stacking (solo stacking and delegation to stacking pools via wallet connect), transaction history monitoring, and real-time balance and staking status updates.

Key features

• Secure authentication: Uses your system's biometric authentication (Touch ID on Mac) or password-based login (Windows and Linux) to protect access. Credentials are stored securely in the OS keychain.
• API credential setup: Guided setup with options to generate a new Certificate Signing Request (CSR) or import existing Fireblocks API credentials.
• Vault account management: View, create, and manage Stacks-enabled vault accounts with real-time balance updates.
• Funds management: Check balances and transfer native STX and custom tokens.
• Transaction history: View detailed transaction records per vault account.
• Stacks staking management: Submit solo stacking requests, delegate to stacking pools, increase locked amounts, extend locking periods, and track real-time staking status and rewards.

Prerequisites

• Fireblocks Raw Signing feature enabled
• Fireblocks API user
• Policy rule in place

Getting started

Download the app

Download the app from our GitHub repository.

First launch

If this is your first time opening the app after downloading it from the developer, you may need to right-click the app icon and select Open to bypass security warnings on macOS.

1. Double-click the Fireblocks x Stacks application icon.
2. When prompted, authenticate using Touch ID (on Mac) or your system's configured authentication method (password on Windows and Linux).
3. After the welcome screen introduces the application, select Get Started to begin setting up your credentials.

Setting up your Fireblocks API credentials

The application requires Fireblocks API credentials to connect to your Fireblocks account. On the API Key Setup screen, you can:

1. Generate a new Certificate Signing Request (CSR): The app guides you through generating an RSA key pair and CSR locally. Download the CSR file, upload it to your Fireblocks Console under Settings > API Users, and retrieve your API key. Paste the API key back into the app to complete setup.
2. Use existing credentials: If you already have a Fireblocks API user and secret key file, import them directly. Browse to select your secret key file and enter your API key.

Once your credentials are validated, the app stores them in the system's keychain and advances to the next setup screen.

Setting up your Hiro API key (optional)

1. This step is optional and can be skipped, but Fireblocks recommends completing it — the Hiro API key significantly improves rate limits and overall user experience. Obtain one for free on the Hiro Platform.
2. On the Secondary Credential Setup screen, enter your Hiro API key.
3. Select Save and Continue. The app validates the key with a health check, then stores it in the system keychain.

Once your key is validated, the app redirects you to the main dashboard.

Main dashboard

The main dashboard shows all your Fireblocks vault accounts with Stacks capability, displaying Stacks balances (STX, USDCx, and sBTC).

Key elements

• Header: Contains the app title, refresh button, notification indicator, and Settings button.
• Search bar: Filter vault accounts by name or ID.
• Refresh button: Refresh the vault account list and update all Stacks balances.
• Create button: Add new vault accounts with automatic Stacks wallet creation.
• Vault account list: Shows your vault accounts and their balances.

Viewing vault account details & transaction history

The vault accounts table shows each vault account's name, ID, and Stacks balances. Select any vault account to view its details page, which includes:

• Account information
• Vault account name and ID
• Stacks address and corresponding BTC rewards address
• Total STX balance
• All owned custom tokens and balances
• Stacking information:
  • Current delegation status
  • Total funds locked
  • Lock period duration

From a vault account's details page, you can also:

• Create Transfer: Send STX and custom tokens to another address or vault account
• Stacking operations:
  • Solo Stacking: Submit a lock funds request
  • Increase amount: Submit a request to increase locked funds
  • Extend period: Submit a request to extend the funds lock period
• Transaction history: View detailed transaction history for both transfers and contract calls, with a View on Explorer option

Creating Stacks transactions

To send funds:

1. Go to the appropriate vault account's details page and select Create Transfer.
2. On the transaction modal, configure the following:
   1. Token: Choose the Stacks token to transfer.
   2. Destination: Enter a recipient Stacks address, or select a vault account from the dropdown.
   3. Amount: Enter the amount to send, or toggle Use Max Amount to send all available tokens.
   4. Fee handling: Choose a gross transaction to deduct the fee from the amount, or leave blank for a net transaction to add the fee to the amount.
3. Review the transaction summary, then select Create Transaction to initiate the transfer.
4. Authenticate with Touch ID (Mac) or your password (Windows and Linux) when prompted.
5. Sign the transaction using the Fireblocks mobile app or automatic Co-signer, per your workspace policy.
6. After confirmation, the transaction appears with processing status until it is confirmed on the Stacks blockchain.

Stacking operations

To lock (stack) STX:

1. Go to the appropriate vault account's details page and select Solo Stack.
2. On the stacking modal, configure the following:
   1. Action: Stack STX, increase amount, or extend period.
   2. Parameters: Enter the parameters relevant to your action.
   3. Signer key and signature: Use the Stacks Stacking Signature Tool to obtain a signer key and generate the signature over the relevant parameters.
3. Review the operation summary, then select Submit to initiate.
4. Sign the transaction using the Fireblocks mobile app or automatic Co-signer, per your workspace policy.
5. After confirmation, the transaction appears with processing status until it is confirmed on the Stacks blockchain.

DApp browser

The desktop application includes a built-in DApp browser for interacting with Stacks-native DeFi applications and stacking pools directly from your Fireblocks vault.

1. Go to DeFi & Staking in the sidebar.
2. Browse the available applications across two categories:
   • DeFi Apps: DEXs, lending protocols, liquid staking, bridges, and other Stacks-native applications.
   • Stacking Pools: Non-custodial delegation pools for earning BTC or STX rewards.
3. Select the application or pool you want to use, then select Open DApp.
4. The DApp opens in an embedded browser inside the application.
5. Select Connect Wallet within the DApp — your Fireblocks vault accounts appear as wallet options.
6. Interact with the DApp as normal. Any transaction it requests is routed through Fireblocks and triggers the standard signing flow.
7. Confirm the operation in the confirmation modal.
8. Sign the transaction using the Fireblocks mobile app or automatic Co-signer, per your workspace policy.
9. After confirmation, the transaction appears with processing status until it is confirmed on the Stacks blockchain.

Settings & security

To access the app's settings, select the gear icon in the bottom-left corner of the app.

Security settings

• Authentication Lock Time: Set how long the app stays authenticated before requiring reauthentication. Enter the number of minutes (1–60), then select Save to apply the new timeout value. When your session next expires, you must reauthenticate with Touch ID or your password.

Credentials management

• Change Fireblocks API Credentials: Remove the current credentials and set up new ones. This requires reauthentication.
• Change Hiro API Key: Update your Hiro API key for Stacks operations.
• Clear All Data: Remove all stored credentials and reset the app to its initial setup state.

Troubleshooting

Some common issues with the Fireblocks x Stacks desktop app include the following.

Authentication problems

• Touch ID not working (Mac): Ensure Touch ID is set up in System Preferences and that the app has permission to use it.
• Authentication timeout too short: Increase the timeout value in Settings.
• Balance not updating: Select the Refresh button on the vault accounts list or in Transaction History.
• Pending transactions: Some transactions may take time to confirm on the blockchain. Check your internet connection and restart the app if the issue persists.

Transaction issues

• Insufficient balance: Ensure you have enough STX to cover the transaction amount plus fees.
• Network congestion: The Stacks network may be experiencing delays. Wait and retry.

Stacking issues

• Lock funds request rejected: The SDK rejects stacking requests submitted during certain time windows when the network cannot process them in time for the current cycle. Wait for the next stacking cycle (which may take up to a few days) and try again.
• Signature error: Verify that the signature was generated using parameters that exactly match those entered in the stacking modal.

API connection errors

• Invalid API key: Verify your Fireblocks API key is correct and has the appropriate permissions for Raw Signing.
• Invalid Hiro API key: Verify your Hiro API key is valid. You can update it in Settings.

Getting support

If you continue to experience issues after troubleshooting, contact your Fireblocks Customer Success Manager and ask for assistance from the Professional Services team.