Transaction Signing Callback Handler

POST /v2/tx_sign_request

This request is used for transaction signing and approval and expects a CallbackResponse object from the callback handler. If the callback handler does not respond within 30 seconds, Fireblocks fails the request. If your callback handler can't respond within 30 seconds, you can use the retry mechanism by responding with RETRY.

If both approval and signing are requested for a transaction, one callback handles both requests.

To differentiate whether this request is for signing, approving, or both, these parameters are included only with signing requests:

fee
displayDstAddress within the transaction's destinations array

Request parameters

Parameter	Type	Description
txId	string	The transaction's internal ID in Fireblocks.
operation	string	The transaction operation type. The default is `TRANSFER`.
sourceType	string	The source of the transaction.
sourceId	string	The transaction’s source vault account ID or exchange account UUID.
destType	string	The transaction's destination type. The type can be VAULT, EXCHANGE, ONE_TIME, or UNMANAGED.
destId	string	The destination's vault account ID or exchange account UUID.
asset	string	The asset ID in Fireblocks.
amount (Deprecated)	number	Use the amountStr field for accuracy. If the transfer is a withdrawal from an exchange, the actual transfer amount. Otherwise, the requested amount.
amountStr	string	The amount of the transfer in string format.
requestedAmount (Deprecated)	number	Use the requestedAmountStr field for accuracy. The requested transfer amount. In gross transactions, transaction fees are deducted from this amount.
requestedAmountStr	string	The requested transfer amount in string format. In gross transactions, transaction fees are deducted from this amount.
fee	string	(Optional) The transaction's estimated fee.
destAddressType	string	The destination's address type. For one-time addresses on EVM-compatible blockchains, this is the smart contract address.
destAddress	string	The destination address of the transaction.
destinations	array	An array of TransactionRequestCallbackDestination objects with all details for all destination(s).
players	array (string)	A list of the Co-signers that signed the transaction. (Two Fireblocks SaaS and at least one user device or one API Co-signer). Each signer is represented by a Device ID.
requestId	string	A unique identifier of this request is returned in the response.
signerId	string	The user that signed the transaction.
extraParameters	object	(Optional) Parameters that are specific to some transaction operation types and blockchain networks. Learn more below.
note	string	(Optional) Custom note that describes this transaction in your Fireblocks workspace. The note isn’t sent to the blockchain.
rawTx	array	An array of RawTX. Contains a list of the actual transaction payload sent to the blockchain. Note that some signing requests represent multiple transactions. When this occurs, the list contains more than one object. This parameter is not included in the CallbackResponse object when using a Fireblocks EU cloud environment. This field is included for the following blockchains: BTC, DASH, DOGE, LTC, BSV, BCH, XEC, ZEC, EVMs, all Cosmos based chains, SOL, XLM, XTZ, TRX, NEAR, XRP and TON. This is an opt-in feature. Please contact Fireblocks Support to include this feature in your workspace. Note: This field appears only for the signing stage of a transaction, and not during the approval stage.
externalTxId	string	An optional but highly recommended parameter. Fireblocks will reject future transactions with same ID. You should set this to a unique ID representing the transaction, to avoid submitting the same transaction twice. This helps with cases where submitting the transaction responds with an error code due to Internet interruptions, but the transaction was actually sent and processed. To validate whether a transaction has been processed, Find a specific transaction by external transaction ID. There is no specific format required for this parameter.
action (deprecated)	object	Includes information about the transaction authorization policy rule that matched this transaction. This field and its contents are not officially supported or maintained. Fireblocks may delete or change the contents of this field at any time.

TransactionOperation

Parameter

Type

Description

operation

string

TRANSFER: Default. Transfers funds from one account to another. UTXO blockchains allow multi-input and multi-output transfers. All other blockchains allow transfers with one source address and one destination address.

MINT: Mints new tokens. Supported for Stellar, Ripple, and EVM-based blockchains.

BURN: Burns tokens. Supported for Stellar, Ripple, and EVM-based blockchains.

CONTRACT_CALL: Calls a smart contract method for web3 operations on any EVM blockchain. The Fireblocks development libraries are recommended for building contract call transactions.

TYPED_MESSAGE: An off-chain message in either Ethereum Personal Message or EIP712 format. Use it to sign specific readable messages that are not actual transactions. Learn more about typed messages.

RAW: An off-chain message with no predefined format. Use it to sign any message with your private key, including protocols such as blockchains and custom transaction types that are not natively supported by Fireblocks. Learn more about raw signing transactions.

ENABLE_ASSET: Algorand, DigitalBits, Solana, and Stellar require an on-chain transaction to create an asset wallet and enable the deposit address. This transaction is automatically created when adding assets on these blockchains to a vault account.

STAKE: Assign assets to a staking pool managed by a staking validator. Learn more about staking transactions and supported blockchains. This transaction is automatically created when performing staking operations.

UNSTAKE: Remove assets from a staking pool managed by a staking validator. Learn more about staking transactions and supported blockchains. This transaction is automatically created when performing staking operations.

WITHDRAW: Transfer assets from a dedicated staking vault account to another address. Learn more about staking transactions and supported blockchains. This transaction is automatically created when performing staking operations.

Note: Fireblocks will rename WITHDRAW to a different name soon. There will be at minimum a 7-day notice regarding the new type name.

TransactionExtraParameters

Parameter	Type	Description
inputsSelection	InputsSelection object	For UTXO-based blockchain multi-input selection, use the `inputsSelection` field with values set to the input selection structure. The inputs can be retrieved using the Retrieve Unspent Inputs endpoint.
rawMessageData	RawMessageData object	For `RAW` operations, use the rawMessageData field with the values set to the raw message data structure.
contractCallData	string	For `CONTRACT_CALL` operations, use the contractCallData field with the value set to the Ethereum smart contract Application Binary Interface (ABI) payload. The Fireblocks development libraries are recommended for building contract call transactions

TransactionRequestCallbackDestination

Parameter	Type	Description
amountNative	number	Deprecated. The amount transferred to this destination as a number. Use the amountNativeStr parameter for accurate precision.
amountNativeStr	string	The amount transferred to this destination represented as a string.
amountUSD	number	The USD value of the transfer to this destination.
dstAddressType	WHITELISTED or ONE_TIME	`WHITELISTED` or `ONE_TIME`
dstId	string	The ID of the destination.
dstName	string	The name of the destination.
dstSubType	string	The specific exchange, fiat account, or unmanaged wallet. For exchange accounts: `BINANCE`, `BINANCEUS`, `BITFINEX`, `BITHUMB`, `BITMEX`, `BITSO`, `BITSTAMP`, `BITTREX`, `BYBIT`, `CIRCLE`, `COINBASEEXCHANGE`, `COINBASEPRO`, `COINMETRO`, `COINSPRO`, `CRYPTOCOM`, `DERIBIT`, `GEMINI`, `HITBTC`, `HUOBI`, `INDEPENDENTRESERVE`, `KORBIT`, `KRAKEN`, `KRAKENINTL`, `KUCOIN`, `LIQUID`, `OKCOIN`, `OKEX`, `PAXOS`, `POLONIEX` For fiat accounts: `BLINC` For unmanaged wallets: `INTERNAL`, `EXTERNAL`, or `CONTRACT`
dstType	string	The destination of the transaction: `VAULT`, `EXCHANGE_ACCOUNT`, `FIAT_ACCOUNT`, or `UNMANAGED`.
displayDstAddress	string	The address of this specific destination
action	string	Includes information about the Transaction Authorization Policy rule that matched this transaction.

RawTX

Parameter	Type	Description
rawTx	string	Hex-encoded details of a transaction sent to the blockchain
keyDerivationPath	string	Location of the encryption key within the customer’s HD Wallet URL used to sign this transaction.