Skip to content
Docs
Start free

Guides

Fireblocks

The Fireblocks API Co-Signer calls Immiscible before it signs each transfer, and signs only when an unused receipt covers it.

Fireblocks documents an outside approval step that runs before signing: the API Co-Signer callback handler. The Co-Signer, which you run and which holds your key share, calls a handler you name before it signs each transaction, and signs only if the handler answers APPROVE. Immiscible can be that handler. It holds no key share, no seed phrase and no funds, and never signs a transaction; the Co-Signer does.

Fireblocks’ documentation: creating a callback handler, secure communication, the response object, approving transactions.

#The exchange, as documented

  • The Co-Signer sends POST {callback URL}/v2/tx_sign_request. The body is a JWT signed RS256 with the Co-Signer’s private key. Its payload carries requestId, txId, operation, asset, amountStr, destAddress, externalTxId, note and more.
  • The handler answers with a JWT signed RS256 with its own RSA-2048 key: { action, requestId, rejectionReason }, where action is APPROVE, REJECT or RETRY.

#How Immiscible answers

The same rule as the card rail: no unused receipt, no signature.

  1. The agent asks POST /v1/actions/authorize with the crypto payment, as on Crypto payments.
  2. On allow, it creates the Fireblocks transaction with the Immiscible action id as externalTxId (or immiscible:<action id> in the note).
  3. The Co-Signer calls Immiscible. Immiscible verifies the request’s signature with the Co-Signer’s public key, then approves only if that action was allowed, its agent is not frozen, its receipt is unused, unrevoked and unexpired, and the transfer matches it: the same destination address, an asset id that names the same asset (USDC, USDC_POLYGON and so on), and amountStr no larger than allowed. Approving uses the receipt up, so it approves one signature.
  4. Anything else, including a request it cannot verify or any error, is a signed REJECT with a reason. Every answer is a wallet_authorization record in the ledger.

What is not checked: the network inside a Fireblocks asset id (asset ids are Fireblocks’ own names, and the mapping to networks is not published in a form Immiscible reads), and the source vault account. Immiscible answers TRANSFER operations only and rejects any other.

#Set it up

  1. In Immiscible, Settings, Connections, choose Connect on the Fireblocks API Co-Signer card and paste the Co-Signer’s public key (PEM). Owners and admins can do this. Immiscible makes the handler’s RSA-2048 key pair and shows the public key and the callback URL, https://<your Immiscible>/wallets/<workspace>/fireblocks.
  2. In your Co-Signer’s setup, give it that callback URL and the handler public key.
  3. In Fireblocks, route the agent’s transactions through the API user whose Co-Signer has the callback.

The API is PUT /api/w/:wid/wallets/fireblocks with { "cosignerPublicKey": "-----BEGIN PUBLIC KEY-----..." }, and DELETE to disconnect.

#Not verified

Tested against a fake Co-Signer that replays the documented request shape and checks the signed answer (test/crypto-wallets.test.js), not against a real Co-Signer. The configuration-change callback (/v2/config_change_sign_request) is not handled.