Skip to main content

​
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. IGNORE applies to approval requests only. 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, but the two stages don’t send an identical payload. Fields below that only appear in one stage are tagged Approval only or Signing only; untagged fields are sent in both.

​
Request parameters

​
Identifiers

​
string
The transaction’s internal ID in Fireblocks.
​
string
A unique identifier of this request is returned in the response. For a batched transaction, this retains the batch suffix that txId does not.
​
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.

​
Signers

​
string
(Optional) The Fireblocks API user ID associated with the cosigner device that’s signing. This identifies the cosigner, not necessarily the person who created the transaction.
​
array
Signing only
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.

​
Transaction details

​
string
The transaction operation type. The default is TRANSFER.
​
string
The asset ID in Fireblocks.
​
number
deprecated
Use the amountStr field for accuracy. If the transfer is a withdrawal from an exchange, the actual transfer amount. Otherwise, the requested amount.
​
string
The amount of the transfer in string format.
​
number
deprecated
Use the requestedAmountStr field for accuracy. The requested transfer amount. In gross transactions, transaction fees are deducted from this amount.
​
string
The requested transfer amount in string format. In gross transactions, transaction fees are deducted from this amount.
​
string
Signing only
The transaction’s estimated fee. Not included in the approval-stage payload at all.
​
number
Signing only
(Optional) The change output index, for UTXO-based blockchains that return change to a Fireblocks address.
​
string
(Optional) Custom note that describes this transaction in your Fireblocks workspace. The note isn’t sent to the blockchain.
​
object
(Optional) Parameters that are specific to some transaction operation types and blockchain networks. Learn more below.
​
array
Signing only
An array of RawTX objects. 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: ADA, 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.

​
Source and destination

​
string
The source of the transaction.
​
string
The transaction’s source vault account ID or exchange account UUID.
​
string
The transaction’s destination type: VAULT, EXCHANGE, ONE_TIME, UNMANAGED, NETWORK_CONNECTION, COMPOUND, NONE, OEC_PARTNER, END_USER_WALLET, GLOBAL_WHITELIST, CONNECTED_ACCOUNT, or LEGACY_TO_NEW_VAULT.
​
string
The destination’s vault account ID or exchange account UUID.
​
string
The destination address of the transaction. Always present at the signing stage; only present at the approval stage when the destination has a resolvable address.
​
string
Signing only
The destination’s address type: WHITELISTED (default) or ONE_TIME. Not included in the approval-stage payload.
​
array
An array of TransactionRequestCallbackDestination objects with all details for all destination(s).

​
Virtual sub-accounts

Present only at the approval stage, only when the transaction’s source or destination is a virtual sub-account of a vault account. Not included in the signing-stage payload.
​
string
Approval only
The virtual (sub-account) type of the transaction source.
​
string
Approval only
The virtual (sub-account) identifier of the transaction source.
​
string
Approval only
The virtual (sub-account) type of the transaction destination.
​
string
Approval only
The virtual (sub-account) identifier of the transaction destination.

​
Trading account and third-party routing

Present only at the approval stage, when the transaction has associated Fireblocks Network routing metadata. Not included in the signing-stage payload.
​
boolean
Approval only
Present whenever network-routing metadata exists on the transaction; true when that routing is through a third party.
​
string
Approval only
(Optional) The type of the underlying source account behind the third-party routing.
​
string
Approval only
(Optional) The identifier of the underlying source account behind the third-party routing.
​
string
Approval only
(Optional) The off-exchange trading account associated with the transaction source.
​
string
Approval only
(Optional) The off-exchange trading account associated with the transaction destination.

​
Protected tags

​
array
(Optional) A list of protected tags attached to the transaction source.

​
TransactionOperation

​
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.SUPPLY, REDEEM, APPROVE, ENTER_MARKET, EXIT_MARKET: DeFi lending-protocol operations.DEPLOYMENT: Deploys a smart contract.PROGRAM_CALL: Calls a Solana program.UPGRADE: Upgrades a deployed program or contract.OFFER_RESPONSE: Responds to a trading offer.

​
TransactionExtraParameters

​
object
For UTXO-based blockchain multi-input selection, use the inputsSelection field with values set to the InputsSelection object. The inputs can be retrieved using the Retrieve Unspent Inputs endpoint.
​
object
For RAW operations, use the rawMessageData field with the values set to the RawMessageData object.
​
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

​
number
deprecated
(Optional) The amount transferred to this destination as a number. Present when this destination carries its own amount metadata (multi-destination transfers). Use the amountNativeStr parameter for accurate precision.
​
string
(Optional) The amount transferred to this destination represented as a string. Same presence condition as amountNative.
​
number
(Optional) The USD value of the transfer to this destination. Same presence condition as amountNative.
​
number
(Optional) Approval-stage only. The original (uncapped) requested amount for this destination, present only when the amount exceeds an internal display cap.
​
string
(Optional) Approval-stage only. String form of originalAmount, under the same condition.
​
string
WHITELISTED or ONE_TIME.
​
string
The ID of the destination.
​
string
The name of the destination.
​
string
(Optional) The ID of the destination’s wallet container, when the destination is an unmanaged or dApp wallet.
​
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, POLONIEXFor fiat accounts: BLINCFor unmanaged wallets: INTERNAL, EXTERNAL, or CONTRACT
​
string
(Optional) The blockchain-level destination tag or memo for this destination (for example, a Ripple destination tag). Distinct from tags below, which holds protected tags, not a blockchain memo.
​
string
VAULT, EXCHANGE, ONE_TIME, UNMANAGED, NETWORK_CONNECTION, COMPOUND, NONE, OEC_PARTNER, END_USER_WALLET, GLOBAL_WHITELIST, CONNECTED_ACCOUNT, or LEGACY_TO_NEW_VAULT.
​
string
(Optional) The address of this specific destination.
​
string
(Optional) The display form of dstTag.
​
string
(Optional) The policy verdict for this specific destination: ALLOW, BLOCK, 2-TIER, SKIP, BYPASS, or ALLOW_NO_AUTHORIZER_DEFINED.
​
object
(Optional) Present alongside action. Details about the policy rule that produced the verdict.
​
object
(Optional) Present only when action is 2-TIER. Describes the approvers required for two-tier authorization, including a logic field (how the groups combine) and a groups array of approval groups. The exact shape varies by policy version; not fully enumerated here.
​
object
(Optional) Present when the destination address was resolved through a reverse lookup (for example, an on-chain naming service).
​
object
(Optional) Additional context about how this destination’s transfer was initiated. Note the wire field name is txAdditionalDetails, not additionalDetails.
​
object
(Optional) Present when this destination is routed through a Fireblocks Network connection.
​
object
(Optional) Enrichment data scoped to this specific destination. Unlike the transaction-level trading account and third-party routing fields above (which only expose a curated subset), this is the full per-destination object, unfiltered.
​
array
(Optional) A list of protected tags attached to this destination — the destination-side counterpart to the top-level sourceTags.

​
RawTX

​
string
Hex-encoded details of a transaction sent to the blockchain.
​
string
Location of the encryption key within the customer’s HD Wallet URL used to sign this transaction.
​
string
The signing payload (typically a transaction hash) computed from rawTx.