Key Link transaction metadata

When Fireblocks Key Link sends a 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 signed txMetaData 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

A KEY_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:

{
  "tenantId": "3827c4de-972e-5641-8a51-0a9f713aa708",
  "txId": "50076a36-4580-4354-b8ea-b8c3e3e85479",
  "keyId": "ae060113-45f3-46bd-9528-aa8a246cf04b",
  "algorithm": "EDDSA_ED25519",
  "type": "KEY_LINK_TX_SIGN_REQUEST",
  "signingDeviceKeyId": "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1",
  "timestamp": 1789404629,
  "messagesToSign": [{ "message": "0201030766...", "index": 0 }],
  "metadata": { "...": "see below" }
}

Transaction signing payloads don’t include a version field.

number

The time the signing request was created, as a Unix timestamp in seconds.

`metadata`

A flat object mixing a transaction summary with lower-level signing details:

string

A JSON-encoded string. Parse it to get the TxMetaData object described below.

array

Signatures over the txMetaData string. Each entry:

Show properties

string

The signer’s identifier. policy_service for the standard signature; can also be a user ID when type is USER_AUTHORIZER.

string

SERVICE (signed by Fireblocks) or USER_AUTHORIZER (signed by a designated approving user, e.g. under a 2-tier policy).

string

A hex-encoded RSA-SHA256 signature of the txMetaData string.

array

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.

Show properties

string

Hex-encoded raw bytes of the message to sign.

array

BIP32-style derivation path segments. Empty ([]) for assets that don’t need one.

(Optional) The raw transaction. Present when additional callback parameters are enabled for your workspace. Can be empty for some blockchains.

(Optional) A signing flag. Entries can carry signing flags such as useKeccak, depending on the blockchain.

number

(Optional) The number of signature operations Fireblocks expects back for this request. Not always sent.

string

The Fireblocks asset ID, e.g. SOL_TEST. A flattened copy of the same value inside txMetaData, kept in sync with it.

string

(Optional) The transaction’s operation type, e.g. TRANSFER. A flattened copy of txMetaData.transactionType. Not always sent.

string

(Optional) The primary destination address. A flattened copy of txMetaData.dstAddress. Not always sent.

string

(Optional) Destination tag or memo, for chains that support one. A flattened copy of txMetaData.dstTag. Not always sent.

number | string

The transaction amount. A number for transfers; the string "0.0" for raw signing.

string

(Optional) The transaction amount as a string, for precision. Absent for raw signing.

string | number

(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.

number

The USD value of the transfer.

number

The network fee, in the asset’s smallest unit.

string

(Optional) The network fee as a decimal string, in base asset units. An empty string for raw signing. Not always sent.

string

Hex-encoded HD wallet chaincode used to derive the signing key for this operation.

string | number

The source ID. Can be a number or a string, so handle both types.

string

The source type, e.g. VAULT.

string

The destination ID.

string

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) Sent for token transfers.

(Optional) The token’s symbol. Sent for token transfers.

(Optional) Sent for XRP transactions where applicable.

(Optional) Sent for UTXO-based transactions where applicable.

Raw signing requests

For raw signing requests, the flat amount fields carry placeholder values:

amount is the string "0.0".
amountInt is the number 0.
coinbaseFee is an empty string ("").
amountStr is absent.

The details of the messages to sign are in txMetaData.extraParameters.rawMessageData. See Operation and chain-specific fields.

Signature verification

Fireblocks Agent verifies the policy_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

string

The transaction’s ID.

string

The workspace (tenant) ID.

string

The transaction’s operation type, e.g. TRANSFER.

string

The Fireblocks asset ID.

Initiator

string

The ID of the user or API user who created the transaction.

string

Usually the same as userId.

string

(Optional) Display name of the initiating user.

(Optional) The type of the initiating user.

(Optional) Initiator-related field, sent on some transactions.

Source

string

The source type, e.g. VAULT.

string

(Optional) The specific source subtype. An empty string when not applicable.

string

The source ID. Always a string here, unlike metadata.srcId (above), which can be a number or a string.

string

(Optional) Display name of the source, e.g. the vault account’s name. Can carry human-identifiable information, so handle it accordingly.

string

(Optional) Set for end-user-wallet sources. An empty string otherwise.

(Optional) Tags associated with the source.

Destination

The dst* fields in this section are conditional. They are omitted for typed message signing and for burns with no destinations.

boolean

Whether this transaction uses the multi-destination destinations array. Note the all-caps wire key, unusual among the otherwise camelCase fields here.

string

(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).

string

(Optional) The specific destination subtype. An empty string when not applicable.

string

(Conditional) ONE_TIME or WHITELISTED.

string

(Optional) The destination’s ID. Empty for one-time addresses.

string

(Optional) Display name of the destination, e.g. an exchange account or vault account name. Can carry human-identifiable information, so handle it accordingly.

string

(Conditional) The primary destination’s address.

string

(Conditional) The display form of dstAddress.

string

(Optional) Destination tag or memo, for chains that support one. Not present for this Solana example.

string

(Optional) The display form of dstTag.

array

Present for multi-destination transactions. One entry per destination. See below.

Amounts and fees

number

The transfer amount.

string

The transfer amount as a string, for precision.

number

The USD value of the transfer.

string

(Optional) The USD exchange rate used to compute amountUSD. Not always present, so don’t treat it as required.

string

The fee level used, e.g. MEDIUM.

string

The asset the fee is paid in.

string

(Optional) The USD exchange rate used for the fee asset. Not always present, so don’t treat it as required.

boolean

(Optional) Whether the fee is deducted from the requested amount. Not always present, so don’t treat it as required.

boolean

(Optional) Whether cash-out is enabled for this transfer.

Additional fee-related and nonce-related keys can appear, depending on the blockchain and the fee settings of the transaction.

Blockchain details

string

The blockchain or network asset ID, e.g. SOL_TEST.

string

The network protocol, e.g. SOL.

boolean

Whether this is a testnet transaction.

string

(Optional) Chain-specific. For Solana, the blockhash used to build the transaction.

string

(Optional) Chain-specific. For Solana, the nonce account address.

Policy verdict

string

The policy verdict for the primary destination, e.g. ALLOW.

object

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.

object

(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.

string

The overall policy verdict for the transaction, e.g. ALLOW. For a single-destination transfer, the same as action.

string

The Fireblocks API or Console user ID designated to sign, per the matched policy rule.

array

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.

object

(Optional) Additional parameters. For raw signing, 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 contract call transactions.

(Conditional) EIP-7702 authorizations, for EVM transactions that include them.

(Conditional) Decoded program call details, for Solana program calls.

(Conditional) Soroban smart contract call data, for Stellar.

(Conditional) Present for NFT transfers.

(Conditional) Present when the transaction carries a Travel Rule message.

Other fields

boolean

(Optional) Related to HAS_DESTINATIONS; whether the multi-destination format is in use.

object

(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.

object

(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.

object

(Optional) Reserved. Usually an empty object ({}).

object

(Optional) Reserved for Fireblocks use. Ignore it.

object

(Optional) Reserved for Fireblocks use. Ignore it.

`destinations`

Present when HAS_DESTINATIONS is true. Each entry:

string

Same value as the top-level dstType for a single-destination transfer.

string

(Optional) An empty string when not applicable.

string

ONE_TIME or WHITELISTED.

string

This destination’s address.

string

(Optional) This destination’s ID. Empty for one-time addresses.

string

The display form of dstAddress.

string

(Optional) This destination’s tag or memo, for chains that support one.

string

(Optional) The display form of dstTag.

string

(Optional) Display name of this destination. Can carry human-identifiable information, so handle it accordingly.

(Optional) The destination wallet ID, where applicable.

(Optional) Address lookup data for this destination, where available.

(Optional) Transfer network details, where applicable.

(Optional) Tags associated with this destination.

number

The amount sent to this destination.

string

Same amount, as a string.

number

The USD value of the amount sent to this destination.

string

The policy verdict for this specific destination.

object

Same shape as the top-level actionInfo above, scoped to this destination.

object

(Optional) Same wire key as the top-level field above, scoped to this destination. Usually an empty object ({}) here.

object

(Optional) Same wire key as the top-level field above, scoped to this destination.

Example

An example metadata field for a Solana transfer (signatures and the payload to sign are shortened):

{
  "signInfo": [{ "payload": "0201030766...", "path": [] }],
  "txMetaData": "{\"transactionType\":\"TRANSFER\",\"asset\":\"SOL_TEST\",\"userName\":\"Jane Doe\",\"srcType\":\"VAULT\",\"srcSubType\":\"\",\"srcId\":\"17\",\"srcName\":\"Test Vault Account\",\"srcWalletId\":\"\",\"txId\":\"50076a36-4580-4354-b8ea-b8c3e3e85479\",\"tenantId\":\"3827c4de-972e-5641-8a51-0a9f713aa708\",\"userId\":\"5d1adaa5-d62f-4628-9066-9f211a94c25b\",\"initiatorId\":\"5d1adaa5-d62f-4628-9066-9f211a94c25b\",\"HAS_DESTINATIONS\":false,\"enrichmentJson\":{\"templateMessageName\":\"TRANSFER_REQUEST\"},\"txAdditionalDetails\":{\"availableBalance\":\"3.899975879\",\"isAutoCalculatedGasLimit\":false,\"useBroadcastingService\":true,\"useBroadcastOrchestrator\":false,\"psv2MultiInstanceFlow\":true},\"dstType\":\"ONE_TIME_ADDRESS\",\"dstSubType\":\"\",\"dstId\":\"\",\"dstAddressType\":\"ONE_TIME\",\"dstAddress\":\"11111111111111111111111111111111111111111\",\"displayDstAddress\":\"11111111111111111111111111111111111111111\",\"amountUsdRate\":\"78.9920978006333\",\"amountNative\":1.0,\"feeLevel\":\"MEDIUM\",\"feeAsset\":\"SOL_TEST\",\"feeUsdRate\":\"78.9920978006333\",\"isGrossAmount\":false,\"enableCashOut\":false,\"blockHash\":\"22222222222222222222222222222222222222222\",\"nonceAccountAddress\":\"33333333333333333333333333333333333333333\",\"networkProtocol\":\"SOL\",\"blockchain\":\"SOL_TEST\",\"testNet\":true,\"transactionConfigurations\":{},\"amountNativeStr\":\"1\",\"amountUSD\":78.9920978,\"multiDestFormat\":false,\"action\":\"ALLOW\",\"actionInfo\":{\"byGlobalPolicy\":false,\"ruleType\":\"TENANT\",\"byRule\":true,\"capturedRuleNumV2\":\"1\",\"rulesSnapshotId\":159191},\"authorizationGroups\":{\"groups\":[]},\"signerId\":\"f6f44913-c8da-4e60-aa81-76ffd02633cc\",\"signerIds\":[\"f6f44913-c8da-4e60-aa81-76ffd02633cc\"],\"policyVerdict\":\"ALLOW\"}",
  "asset": "SOL_TEST",
  "dstAddress": "11111111111111111111111111111111111111111",
  "amountStr": "1.000000000",
  "amount": 1.0,
  "amountInt": "1000000000",
  "fee": 19000,
  "coinbaseFee": "0.000019000",
  "srcId": 17,
  "srcType": "VAULT",
  "destId": "",
  "destType": "ONE_TIME",
  "chaincode": "0000000000000000000000000000000000000000000000000000000000000000",
  "txMetaDataSignatures": [
    { "id": "policy_service", "type": "SERVICE", "signature": "7845f537..." }
  ],
  "signingCount": 1,
  "amountUSD": 78.9920978
}

Changes to this page

14 October 2026: Corrected the types of metadata.srcId, amount, and amountInt. Documented raw signing values, additional signInfo properties, token and chain-specific flat fields, conditional txMetaData and destinations fields, and the top-level timestamp field. Marked flat fields that some paths omit as optional. Removed the statement that version is sent in signing payloads. Added the Stability section.

Get Started

Transactions

API Co-Signers

Webhooks

Workspace & Security

Identity & Compliance

Manage Wallets

Smart Contracts & Tokenization

Treasury & Trading

Gas Management

Payments

Embedded Wallets

Offchain Signing

Direct Custody Wallets

Integrations

Assets & NFTs

Canton

Key Link

Stability

Where this appears

`metadata`

Raw signing requests

Signature verification

`TxMetaData`

Identifiers

Initiator

Source

Destination

Amounts and fees

Blockchain details

Policy verdict

Operation and chain-specific fields

Other fields

`destinations`

Example

Changes to this page

​Stability

​Where this appears

​metadata

​Raw signing requests

​Signature verification

​TxMetaData

​Identifiers

​Initiator

​Source

​Destination

​Amounts and fees

​Blockchain details

​Policy verdict

​Operation and chain-specific fields

​Other fields

​destinations

​Example

​Changes to this page

Stability

Where this appears

`metadata`

Raw signing requests

Signature verification

`TxMetaData`

Identifiers

Initiator

Source

Destination

Amounts and fees

Blockchain details

Policy verdict

Operation and chain-specific fields

Other fields

`destinations`

Example

Changes to this page