Fireblocks Python SDK

Common errors

• ModuleNotFoundError: No module named 'fireblocks_sdk'

  cause The `fireblocks-sdk` package is either not installed, or the import statement uses an incorrect module name (e.g., `import fireblocks` instead of `from fireblocks_sdk import FireblocksSDK`).
  fix Install the package correctly using `pip install fireblocks-sdk` and ensure your Python code uses `from fireblocks_sdk import FireblocksSDK`.

• FireblocksApiException: 403 Forbidden - Authentication Error: Invalid API Key or Signature

  cause The provided `api_key` or `private_key` (secret key) is incorrect, malformed, or the API user associated with the credentials lacks the necessary permissions for the requested operation.
  fix Verify that `FIREBLOCKS_API_KEY` and the content of your private key (from `FIREBLOCKS_SECRET_KEY_PATH` or `FIREBLOCKS_SECRET_KEY`) are correct. Check the Fireblocks Console under 'Developer Center > API Users' to ensure the API user has the required workspace roles and permissions.

• requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response')) or similar 500 Internal Server Error

  cause This often indicates a network connectivity issue, an incorrect `base_url` for the Fireblocks API, or a transient server-side problem on the Fireblocks platform. It could also mean an invalid request body leading to a server error.
  fix Confirm network connectivity. Verify that `FIREBLOCKS_BASE_PATH` is set to the correct Fireblocks environment endpoint (e.g., `https://sandbox-api.fireblocks.io/v1` for sandbox, `https://api.fireblocks.io/v1` for production). Review your request payload for correctness. If persistent, check the Fireblocks system status page or contact Fireblocks support with the `x-request-id` from the error response if available.

Warnings

• breaking Recent minor versions within the 2.x series have included 'Maintenance - Breaking Changes' related to API schema updates (e.g., TAP endpoints, `addAssetToExternalWallet` request schema). While SDK method signatures generally remain stable, changes to request/response Data Transfer Objects (DTOs) may require adjustments to your code.
  Fix: Review the GitHub release notes and API documentation for `fireblocks-sdk-py` for affected API endpoints and adjust your request/response models accordingly. Pay close attention to schema changes for `CreateVaultAccountRequest`, `AddAssetToExternalWalletRequest`, and TAP-related operations.
• gotcha The `private_key` (API Secret Key) is crucial for cryptographically signing all API requests. Improper handling (e.g., hardcoding, incorrect file path, or insufficient permissions on the key file) can lead to `403 Forbidden` errors or critical security vulnerabilities.
  Fix: Always load the private key securely, preferably from a file specified by an environment variable (e.g., `FIREBLOCKS_SECRET_KEY_PATH`) and ensure proper file permissions. Avoid exposing it directly in source code or insecure environment variables.
• gotcha The Fireblocks Python SDK officially requires Python 3.8 or newer. Using older Python versions might lead to compatibility issues, unexpected errors, or missing features.
  Fix: Ensure your development and deployment environments are running Python 3.8 or a later supported version. Upgrade Python if necessary.

Install

• pip install fireblocks-sdk Install latest version

Imports

• FireblocksSDK
  wrong:

  import fireblocks

  correct:

  from fireblocks_sdk import FireblocksSDK

  The PyPI package is `fireblocks-sdk`, but the main class is imported from `fireblocks_sdk`.

Quickstart

Initializes the Fireblocks SDK using API key and secret, then fetches a list of vault accounts. It demonstrates secure loading of credentials via environment variables and basic error handling.

import os
from fireblocks_sdk import FireblocksSDK
from fireblocks_sdk.sdk import FireblocksApiException

# Ensure environment variables are set for API Key and Secret
# export FIREBLOCKS_API_KEY="<your_api_key>"
# export FIREBLOCKS_SECRET_KEY_PATH="./fireblocks_secret.key" (or content in FIREBLOCKS_SECRET_KEY env var)
# export FIREBLOCKS_BASE_PATH="https://sandbox-api.fireblocks.io/v1" (or production URL)

try:
    api_key = os.environ.get('FIREBLOCKS_API_KEY', '')
    # It's recommended to load the private key from a file, not directly from an env var
    # For simplicity, using a placeholder here; in production, load securely.
    # For this quickstart, let's assume the secret key is in an environment variable 
    # or a known path for demonstration, but typically it's a file path.
    secret_key_path = os.environ.get('FIREBLOCKS_SECRET_KEY_PATH')
    if secret_key_path and os.path.exists(secret_key_path):
        with open(secret_key_path, 'r') as f:
            private_key = f.read()
    else:
        private_key = os.environ.get('FIREBLOCKS_SECRET_KEY', '')
        print("Warning: Loading private key directly from environment variable. Consider using a file path for security.")

    base_url = os.environ.get('FIREBLOCKS_BASE_PATH', 'https://sandbox-api.fireblocks.io/v1')

    if not api_key or not private_key:
        raise ValueError("FIREBLOCKS_API_KEY and FIREBLOCKS_SECRET_KEY/FIREBLOCKS_SECRET_KEY_PATH must be set.")

    fireblocks = FireblocksSDK(private_key=private_key, api_key=api_key, base_url=base_url)
    
    # Fetch and print vault accounts
    vault_accounts = fireblocks.get_vault_accounts()
    print("Successfully connected to Fireblocks and fetched vault accounts.")
    if vault_accounts:
        print(f"First vault account name: {vault_accounts[0].name}")
    else:
        print("No vault accounts found.")

except FireblocksApiException as e:
    print(f"Fireblocks API Error: {e.status_code} - {e.message}")
except ValueError as e:
    print(f"Configuration Error: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")