Fireblocks Integration

For sandbox/testing environments, use the following endpoint:

https://sandbox-fireblocks.deframe.io

This guide explains how clients with Fireblocks custody can integrate with our Smart Wallet and Strategy system, including deposits, withdrawals, position tracking, and recommended security best practices.

Overview

The integration leverages Smart Wallets to provide segregated user accounts while keeping your Omnibus wallet isolated from strategy bytecode execution. This architecture ensures maximum security by preventing your main operational wallet from signing potentially untrusted transactions.

Prerequisites

Before starting the integration, ensure you have:

• A Fireblocks account with API access

• Understanding of Fireblocks Transaction Authorization Policy (TAP)

• Familiarity with our Architecture Overview

---

1. Fireblocks Setup

To safely interact with strategy bytecode while isolating your Omnibus wallet, Fireblocks must be configured with dedicated roles and policies.

Creating Roles

To ensure clean separation of responsibilities and secure execution:

Role	Description
Initiator	The API user or service responsible for submitting strategy-related transactions to Fireblocks. This user will call Fireblocks when signing strategy bytecode.
Earn Owner	A dedicated vault that acts as the Smart Wallet Owner. This address serves as the signer for smart wallet transactions, providing security segmentation from your main operational wallet.

Creating Policies

Two policies must be configured in Fireblocks to ensure automated, safe signing of transactions:

Contract Call Policy

Setting	Value
Initiator	The API user created for strategy operations
Source	Earn Owner vault
Signer	Co-signer (for automatic signing)

Typed Message Policy

Setting	Value
Initiator	The API user created for strategy operations
Source	Earn Owner vault
Signer	Co-signer (for automatic signing)

---

2. Smart Wallet Creation

Each user receives their own segregated smart wallet. Create one by calling:

POST /fireblocks-smart-account

Request Body:

Parameter	Type	Description
owner	string	Who will be the owner of the smart wallet
chainId	number	The blockchain network ID

Response:

{
	"address": "0xE45a91BFb07Ca9c7Be975fe22D37e2FF360454fF",
	"owner": "0xC6946d0221135bba970Fa5BfCE67d8f4094631e5",
	"chainId": 137
}

---

3. Store the Smart Wallet Mapping

You must store the mapping between your internal user IDs and their smart wallet addresses:

userId → smartWalletAddress

This mapping enables you to:

• Display user balances and yield

• Track user performance

• Execute operations on behalf of users

---

4. Deposit Flow

When a user wants to deposit into a strategy (e.g., 100 USDC):

Step 1: Transfer Funds to Smart Wallet

Transfer the deposit amount from your Omnibus wallet to the user's smartWalletAddress.

Step 2: Request Strategy Bytecode

Fetch the bytecode for the deposit operation:

GET /strategies/:id/bytecode?action=lend&amount=100000000&wallet=0x...

See How to Deposit for detailed parameter information.

Step 3: Sign and Execute via Fireblocks

1. Use the Earn Owner signer (NOT the Omnibus signer) to sign the transaction

2. Execute the returned bytecode through Fireblocks

3. The transaction will deposit funds from the smart wallet into the strategy

---

5. View User Positions and Yield

To fetch a user's position, balance, or yield:

GET /wallets/:smartWalletAddress

This endpoint provides all data needed for user-facing dashboards and reporting. See How to Check Open Positions for more details.

---

6. Withdrawal Flow

Withdrawals follow the reverse flow:

Step 1: Request Withdrawal Bytecode

GET /strategies/:id/bytecode?action=withdraw&amount=100000000&wallet=0x...

Step 2: Sign and Execute

Sign and execute the transaction using the Earn Owner signer through Fireblocks.

Step 3: Transfer Funds

After the withdrawal completes, transfer funds from the smart wallet to the destination:

• Back to your Omnibus wallet, or

• Any other target address

---

Trade-offs

Considerations

Aspect	Details
Additional Transfers	Requires two separate transfers for deposits and withdrawals: Transfer IN (Omnibus to Smart Wallet) and Transfer OUT (Smart Wallet to destination)

Benefits

Benefit	Details
Omnibus Isolation	Your Omnibus signer is never exposed to potentially malicious bytecode, preventing scenarios similar to known custody exploits
User Segregation	Each user operates through a fully segregated smart wallet
Auditability	Clean audit trail and easier accounting per user
Analytics	Aggregated deposit analytics available via the /analytics endpoint

---

Optional: Additional Security Layer

For maximum security, you can integrate Blockaid to simulate and validate bytecode before signing it on Fireblocks.

This adds defense-in-depth by detecting:

• Unexpected contract behavior

• Malicious payloads

• Incorrect calldata or parameters

---

Next Steps

• How to Deposit

• How to Withdraw

• How to Check Open Positions