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
| Parameter | Type | Description |
|---|---|---|
| requestId | string | Unique identifier for the call; returned in the response. |
| txId | string | The transaction's internal ID on Fireblocks. |
| operation | TransactionOperation | (Optional) The transaction operation type. The default is TRANSFER. |
| sourceType | string | The source of the transaction. |
| sourceId | string | The source's vault account ID or exchange account UUID. |
| destType | string | The destination of the transaction. |
| destAddressType | string | The destination's address type. For one-time addresses on EVM-compatible blockchains, this is the smart contract address. |
| destId | string | The destination's vault account ID or exchange account UUID. |
| asset | string | The asset symbol. |
| amount | number | The amount of the transfer. |
| amountStr | string | The amount of the transfer represented as a string. |
| requestedAmount | string | The requested amount to withdraw. In gross transactions, this can be a different amount than the transferred amount. |
| destAddress | string | The destination address of the transaction. |
| fee | string | (Optional) The transaction's fee. |
| note | string | (Optional) The note to send with the transaction body request. |
| destinations | array (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 object | Any parameters specific to a protocol or an operation. |
| rawTx | array (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. |
| players | array (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
| Parameter | Type | Description |
|---|---|---|
| requestId | string | Unique identifier for the call; taken from the request. |
| type | string | UNMANAGED_WALLET, EXCHANGE, FIAT_ACCOUNT |
| extraInfo | JSON object | Can be either the AddressInfo or ThirdPartyInfo JSON object. |
Co-Signer data objects
AddressInfo
| Parameter | Type | Description |
|---|---|---|
| subType | string | The exchange account, fiat account, or unmanaged wallet (INTERNAL, EXTERNAL). |
| walletName | string | The wallet's name in the workspace. |
| walletId | string | The wallet's internal ID on Fireblocks. |
| asset | string | The wallet's asset. |
| address | string | The asset's address in the wallet. |
| tag | string | (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
| Parameter | Type | Description |
|---|---|---|
| action | string | APPROVE, REJECT, IGNORE |
| requestId | string | The unique identifier of the call; was received in the approval request. |
| rejectionReason | string | Free text of the reason for rejection; for logging purposes. |
ThirdPartyInfo
| Parameter | Type | Description |
|---|---|---|
| subType | string | The exchange account, fiat account, or unmanaged wallet (INTERNAL, EXTERNAL). |
| accountName | string | The account's name. |
| accountId | string | The account's ID. |
| apiKey | string | The third-party service's API key. |
| addresses | string | (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. |