API Co-Signer

Overview

The API Co-Signer is a component that holds an MPC key share of your Fireblocks Vault and a Configuration Change Key for automated signing and approvals. The key share is used to securely sign transactions initiated via the API. The Configuration Change Key is used to approve new unmanaged wallet additions in the Vault.

You can provision the API Co-Signer with a Co-Signer Callback Handler. The Callback Handler is a predefined HTTPS server that receives signing requests from the API Co-Signer and returns either an approval or rejection response.

Learn more about setting up the Callback Handler.

Automated Signer Callback

When your API Co-Signer is configured with a callback, it sends a POST request to the Callback Handler. The Callback Handler should then respond with the APPROVE, REJECT or IGNORE action.

📘

Note

The IGNORE action can only be returned for transaction authorization or a configuration change.

The POST request contains a JSON Web Token (JWT) encoded message signed with the API Co-Signer's private key. The Callback Handler uses the API Co-Signer's public key to verify every incoming JWT is signed correctly by the API Co-Signer.

The Callback Handler's response is a JWT-encoded message signed with the Callback Handler's private key. The private key must be the key paired with the public key provided to the API Co-Signer during the Callback Handler's setup.

Transaction Signing Callback Handler

POST /v2/tx_sign_request

This request returns a CallbackResponse object.

Request parameters

ParameterTypeDescription
requestIdstringUnique identifier for the call; returned in the response.
txIdstringThe transaction's internal ID on Fireblocks.
operationTransactionOperation(Optional) The transaction operation type. The default is TRANSFER.
sourceTypestringThe source of the transaction.
sourceIdstringThe source's vault account ID or exchange account UUID.
destTypestringThe destination of the transaction.
destAddressTypestringThe destination's address type. For one-time addresses on EVM-compatible blockchains, this is the smart contract address.
destIdstringThe destination's vault account ID or exchange account UUID.
assetstringThe asset symbol.
amountnumberThe amount of the transfer.
amountStrstringThe amount of the transfer represented as a string.
requestedAmountstringThe requested amount to withdraw. In gross transactions, this can be a different amount than the transferred amount.
destAddressstringThe destination address of the transaction.
feestring(Optional) The transaction's fee.
notestring(Optional) The note to send with the transaction body request.
destinationsarray (TransactionRequestCallbackDestination)For UTXO-based blockchains, multiple destinations are supported. For EVM-compatible chains, this array shows the transaction's destination address. For all other blockchains, this array is always composed of one element.
extraParameters(Optional) JSON objectAny parameters specific to a protocol or an operation.
rawTxarray (RawTx)A list of the actual transactions sent to the blockchain. Note that some transactions represent multiple transactions. When this occurs, the list contains more than one object.
playersarray (string)A list of the three Co-Signers that signed the transaction (2 in Fireblocks SaaS + 1 user device or 1 API Co-Signer). Each signer is represented by a Device ID.

Configuration Approval Callback Handler

POST /v2/config_change_sign_request

This request returns a CallbackResponse object.

Request parameters

ParameterTypeDescription
requestIdstringUnique identifier for the call; taken from the request.
typestringUNMANAGED_WALLET, EXCHANGE, FIAT_ACCOUNT
extraInfoJSON objectCan be either the AddressInfo or ThirdPartyInfo JSON object.

Co-Signer data objects

AddressInfo

ParameterTypeDescription
subTypestringThe exchange account, fiat account, or unmanaged wallet (INTERNAL, EXTERNAL).
walletNamestringThe wallet's name in the workspace.
walletIdstringThe wallet's internal ID on Fireblocks.
assetstringThe wallet's asset.
addressstringThe asset's address in the wallet.
tagstring(Optional) Can be the tag or memo for assets that require it, such as EOS, XLM, and XRP; or can be the Bank Transfer Description for fiat providers, such as Signature, Silvergate, and BCB Group.

CallbackResponse

ParameterTypeDescription
actionstringAPPROVE, REJECT, IGNORE
requestIdstringThe unique identifier of the call; was received in the approval request.
rejectionReasonstringFree text of the reason for rejection; for logging purposes.

ThirdPartyInfo

ParameterTypeDescription
subTypestringThe exchange account, fiat account, or unmanaged wallet (INTERNAL, EXTERNAL).
accountNamestringThe account's name.
accountIdstringThe account's ID.
apiKeystringThe third-party service's API key.
addressesstring(Optional) A JSON-formatted "key":"value" string, where "key" is an asset symbol and "value" is its address. There can be multiple entries in the JSON. Use supported_assets to retrieve asset symbols.