KEY_LINK_TX_SIGN_REQUEST message to your Fireblocks Agent, the request carries the transaction details, mainly in the metadata field. Fireblocks Agent forwards this message to your customer server (the /messagesToSign endpoint you implement) exactly as received, so your server can inspect these details (for example, to confirm the amount and destination match what you expect) before authorizing your HSM or key management system to sign.
Parse this structure defensivelyThe fields on this page are not an exhaustive list. Requests can contain fields that aren’t documented here, and Fireblocks can add fields at any time. An unknown or undocumented field must never break your integration.
metadata does not have a fixed, versioned schema. The same field name can carry different values at different nesting levels of the same request; this page calls those cases out.If your integration reads these fields:- Ignore fields you don’t recognize instead of failing, and don’t reject a request because it contains one.
- Don’t assume that a field marked optional or conditional is always present, or that its type stays the same across transaction types.
- Don’t hard-fail your signing flow solely because a field is missing, unless you’ve deliberately decided to require it.
Stability
The core fields are stable: the transaction ID, the asset, the amounts, the source and destination, and the policy verdict. Other fields are informational, and Fireblocks may add new ones over time. Base your signing decisions on the signedtxMetaData object, which Fireblocks Agent verifies before forwarding the request, rather than on the unsigned flat fields in metadata. The flat fields are convenience copies and aren’t covered by any signature.
Where this appears
AKEY_LINK_TX_SIGN_REQUEST you receive at /messagesToSign is a MessageEnvelope, where message.payload is a stringified JSON object. Parsing it gives you a MessagePayload:
version field.
metadata
A flat object mixing a transaction summary with lower-level signing details:
A JSON-encoded string. Parse it to get the TxMetaData object described below.
The raw payloads to be signed, prior to their appearance in
messagesToSign. A request can contain multiple entries, for example when the transaction needs signatures from additional signer paths.(Optional) The number of signature operations Fireblocks expects back for this request. Not always sent.
The Fireblocks asset ID, e.g.
SOL_TEST. A flattened copy of the same value inside txMetaData, kept in sync with it.(Optional) The transaction’s operation type, e.g.
TRANSFER. A flattened copy of txMetaData.transactionType. Not always sent.(Optional) The primary destination address. A flattened copy of
txMetaData.dstAddress. Not always sent.(Optional) Destination tag or memo, for chains that support one. A flattened copy of
txMetaData.dstTag. Not sent on all paths: for example, XRP and Stellar transfers carry the tag only in txMetaData.dstTag, so read it from there.The transaction amount. A number for transfers; the string
"0.0" for raw signing and typed messages.(Optional) The amount in the asset’s smallest unit (e.g. lamports for SOL). A string for transfers; the number
0 for raw signing. Not always sent.The USD value of the transfer. The type depends on the blockchain: a string for most blockchains (for example EVM, Bitcoin, XRP, and Stellar) and a number for others (for example Solana). The string
"0.0" for raw signing and typed messages. Handle both types, or use txMetaData.amountUSD, which is a number.(Optional) The network fee as a decimal string, in base asset units. An empty string for raw signing. Not always sent.
The destination type, e.g.
ONE_TIME. Can also carry policy values such as ONE_TIME_ADDRESS, so it doesn’t always match txMetaData.dstType.(Optional) Chain-specific. Sent for some blockchains only; for example, XRP sends it, as an empty string on native transfers, while EVM token transfers don’t. To identify the token, use
txMetaData.asset.Raw signing and typed message requests
For raw signing and typed message requests, the flat amount and destination fields carry placeholder values:amountandamountUSDare the string"0.0".amountIntis the number0.coinbaseFeeanddstAddressare empty strings ("").destTypeisNONE.amountStris absent.
txMetaData.extraParameters.rawMessageData. See Operation and chain-specific fields.
Signature verification
Fireblocks Agent verifies thepolicy_service entry in txMetaDataSignatures against the Fireblocks signing certificate before it calls your /messagesToSign endpoint. If that signature doesn’t validate, Fireblocks Agent discards the message and never forwards it to your server, so by the time your server receives a request, this check has already passed. Fireblocks Agent checks the policy_service entry; it doesn’t verify USER_AUTHORIZER entries.
If you want to verify the signature again on your side as an additional check, the algorithm is RSA with SHA-256 over the raw txMetaData string, and the signature is hex-encoded.
TxMetaData
The object you get from parsing txMetaData. It uses the same transaction and destination model as the API Co-signer callback handler’s transaction payload, though field values aren’t guaranteed to line up between the two (see the callouts below).
Identifiers
Initiator
Source
The source ID. Always a string here, unlike
metadata.srcId (above), which can be a number or a string.(Optional) Display name of the source, e.g. the vault account’s name. Can carry human-identifiable information, so handle it accordingly.
Destination
Thedst* fields in this section are conditional. They are omitted for typed message signing and for burns with no destinations.
Whether this transaction uses the multi-destination
destinations array. Note the all-caps wire key, unusual among the otherwise camelCase fields here.(Conditional) The primary destination’s type, e.g.
ONE_TIME_ADDRESS. This value doesn’t necessarily match the dstType enum documented for the API Co-signer callback handler (ONE_TIME_ADDRESS here vs. ONE_TIME there, for what’s otherwise the same kind of destination).(Optional) Display name of the destination, e.g. an exchange account or vault account name. Can carry human-identifiable information, so handle it accordingly.
(Optional) Destination tag or memo, for chains that support one. Not present for this Solana example.
One entry per destination. Can be present for single-destination transactions too, so don’t rely on
HAS_DESTINATIONS to decide whether to read it. See below.Amounts and fees
(Optional) The USD exchange rate used to compute
amountUSD. Not always present, so don’t treat it as required.(Optional) The USD exchange rate used for the fee asset. Not always present, so don’t treat it as required.
(Optional) Whether the fee is deducted from the requested amount. Not always present, so don’t treat it as required.
Blockchain details
Policy verdict
Details about the policy rule that produced the verdict. Same shape as
actionInfo in the API Co-signer callback handler payload: ruleType, byGlobalPolicy, byRule, capturedRuleV2, capturedRuleNumV2, rulesSnapshotId, and others.(Optional) Present when two-tier authorization applies. Same shape as
authorizationGroups in the API Co-signer callback handler payload; the exact shape varies by policy version. Observed as {"groups": []} when not applicable.The overall policy verdict for the transaction, e.g.
ALLOW. For a single-destination transfer, the same as action.The full list of designated signer IDs. For a
SINGLE designation, a single-element array matching signerId.Operation and chain-specific fields
These fields appear only for specific operations or blockchains. Their inner structure isn’t documented here; treat them as optional and parse them defensively.(Optional) Additional parameters. For raw signing and typed messages, contains
rawMessageData, which describes the messages to sign: messages[] (each with content), derivationPath, algorithm, and preHash. Can also contain internal instrumentation such as sendToCoreStartTime (a Unix timestamp in milliseconds).(Conditional) Contract call data, for some contract call transactions. Not always present: contract calls can carry the decoded call in
txAdditionalDetails.rawDecodedContractCall instead, with the contract name and the function calls with their parameters.Other fields
(Optional) Enrichment data. Shares its wire key with
enrichmentJson in the API Co-signer callback handler payload, but the fields actually present vary by context. This is a loosely-typed bag, not a fixed schema. Observed here containing only templateMessageName (a string), which isn’t part of the schema documented on that page.(Optional) Additional context about how the transfer was initiated. Same wire key as
txAdditionalDetails in the API Co-signer callback handler payload, but again a loosely-typed bag. The fields observed here (availableBalance, isAutoCalculatedGasLimit, useBroadcastingService, useBroadcastOrchestrator, psv2MultiInstanceFlow) don’t match the fields documented on that page.destinations
One entry per destination. Can be present even when HAS_DESTINATIONS is false, for example with a single destination. Each entry:
(Optional) Display name of this destination. Can carry human-identifiable information, so handle it accordingly.
(Optional) Same wire key as the top-level field above, scoped to this destination. Usually an empty object (
{}) here.Examples
Solana transfer
An examplemetadata field for a Solana transfer (signatures and the payload to sign are shortened):
Other transaction types
The examples below are testnet requests. Long values (payloads, raw transactions, signatures, and chaincodes) are shortened, IDs and addresses are placeholders, and some internal fields are omitted.txMetaData is shown parsed for readability; in the request it’s a JSON string.
- EVM transfer
- ERC-20 transfer
- Contract call
- Bitcoin
- XRP
- Stellar
- Raw signing
- Typed message (EIP-712)
- Typed message (personal sign)
A native ETH transfer on Sepolia to a one-time address.
metadata:txMetaData, parsed:Changes to this page
- 29 October 2026: Corrected the type of
metadata.amountUSD(number or string, depending on the blockchain) and documented whensignInfo[].rawTx, the flatdstTag,tokenBlockchainIdandtokenSymbolare sent. Documented placeholder values for typed message requests and the decoded contract call intxAdditionalDetails. MarkedfeeLevelas optional. Clarified thatdestinationscan be present whenHAS_DESTINATIONSisfalse. Added examples for EVM transfers, ERC-20 transfers, contract calls, Bitcoin, XRP, Stellar, raw signing, and typed messages. - 14 October 2026: Corrected the types of
metadata.srcId,amount, andamountInt. Documented raw signing values, additionalsignInfoproperties, token and chain-specific flat fields, conditionaltxMetaDataanddestinationsfields, and the top-leveltimestampfield. Marked flat fields that some paths omit as optional. Removed the statement thatversionis sent in signing payloads. Added the Stability section.