Fireblocks Payment Method — Self-Serve Integration Guide

How your organization connects its own Fireblocks workspace to Toku and pays crypto payment batches directly from its Fireblocks vaults. Setup takes a few minutes in Toku plus an approval step in Fireblocks.

---

What this integration does

Connecting Fireblocks lets an organization fund crypto payment batches straight from its own Fireblocks vault accounts. Key properties of the design:

• One integration covers the whole workspace. Payment batches automatically match each payment's token and network against the Fireblocks workspace, so every network and asset enabled in the workspace is usable - there is no per-network setup.
• The org keeps custody. Toku never holds the org's funds or workspace credentials beyond an API user the org itself creates - and can disable at any time from the Fireblocks Console.
• Split credentials. Toku generates an RSA signing key that never leaves Toku's server; only the public CSR is shared with Fireblocks. The API key alone is useless without the private signing key, and the private key is useless without the API key.
• Verified before saved. Toku makes a live authenticated call to Fireblocks before storing anything. A bad credential is never persisted.

---

Before you start

Where to find it in Toku: open Admin Integrations → Payment Integrations → Fireblocks card. The card opens the Fireblocks setup window used throughout this guide.

---

Step 1 - Generate the signing key and download the CSR (in Toku)

1. In the Fireblocks setup window in Toku, click Generate signing key.
2. Toku generates an RSA key pair server-side. The private key is stored on the server and never leaves it — what you see is only the CSR (Certificate Signing Request), which is public and safe to share with Fireblocks.
3. Click Download CSR (saves fireblocks.csr) or Copy CSR.

⚠️ Do not press Regenerate casually. Regenerating creates a brand-new signing key and CSR - the existing API user pairing stops working immediately, and payouts are down until you upload the new CSR to Fireblocks, create a new API user, and save its API key in Toku.

---

Step 2 - Create the API user in the Fireblocks Console

1. Open the Fireblocks Console → Developer Center → API users:

• Production: https://console.fireblocks.io/v2/developer/api-users
• Sandbox (only when testing against a Toku test environment): https://sandbox.fireblocks.io/v2/developer/api-users

1. Click Add API user and fill in:

• Name: something recognizable, e.g. toku-api-key.
• Role: Editor — this lets the API user initiate transactions but not change workspace settings.
• Switch the CSR tab to Custom CSR and upload the fireblocks.csr you downloaded in Step 1. (Do not use Automatic CSR - that would generate a key pair Toku doesn't hold.)

1. Click Add user.

1. Approve the new API user. A workspace Owner must approve the pending API user (typically in the Fireblocks mobile app). Until it shows as active in the API users list, Toku's verification in Step 3 will fail.
2. Copy the API key (a UUID) from the API users list - the copy icon next to the key column.

🔐 The API key is not a secret on its own - every API request must also be signed with the private signing key that only Toku's server holds. Still, treat it like a credential: paste it into Toku and don't leave it lying around in chats or docs.

---

Step 3 - Paste and verify the API key (in Toku)

1. Back in Toku, paste the API key into Fireblocks API key.
2. Click Verify & save API key.

What happens when you click the button:

• Toku makes a live authenticated call to Fireblocks using your API key plus the server-held signing key.
• The key is only persisted if Fireblocks accepts the credentials. On failure nothing is saved, and the failure is audit-logged.
• Once saved, the key is never displayed again — Toku shows only a masked version (last 4 characters). Leaving the field blank on later saves keeps (and re-verifies) the stored key.
• One key covers the whole workspace - all networks and assets. When verification succeeds the integration badge flips to Active.

---

Step 4 - (Optional) Set a default payout route for token grants

This step only matters if the org uses the token-grants settlement flow. Regular payment batches ignore this default - they resolve each payment's token and network against the Fireblocks workspace dynamically.

1. Pick a Default network (the list shows the org's enabled networks).
2. Search for a Default asset by symbol or name - the list comes live from your Fireblocks workspace catalog and shows each asset's Fireblocks API ID.
3. Click Save default route. (Reset clears both.)

---

Step 5 - Link payout vault wallets

Payouts are funded from the vault accounts you link here. At least one linked vault is required before Fireblocks appears as a payout option when creating payment batches.

1. The dropdown lists the vault accounts in your Fireblocks workspace (already-linked vaults are hidden).
2. Select the vault that should fund payouts and click Link vault.
3. Linked vaults appear above the dropdown with their vault ID and address. Link as many as you need.

---

Confirm it's live

• [ ] The Fireblocks card under Payment Integrations shows Connected, and the setup window badge shows Active.
• [ ] At least one vault wallet is listed under Payout vault wallets.
• [ ] Fireblocks appears as a payout option when creating a payment batch.
• [ ] Run a small test payout end-to-end before the first real batch - this proves vault funding, gas, and the workspace policy in one go.

---

Fireblocks workspace settings that affect payouts

These live entirely in the Fireblocks Console and are the most common reason a connected integration still can't pay:

1. Transaction Authorization Policy (TAP). Transfers initiated by the API user follow the workspace's TAP. If the matching rule requires approval, every payout sits in pending approval until a designated approver signs it in the Fireblocks mobile app. Decide up front whether API-initiated payouts should auto-approve or who approves them - and know that a stuck transaction can be cancelled from the Fireblocks Console, after which the batch can be retried.
2. One-time (non-whitelisted) addresses. Payouts go to recipients' wallet addresses, which are usually not whitelisted in the workspace. The workspace must allow transfers to one-time addresses, or the destination addresses must be whitelisted first.
3. Vault funding. The linked vault needs the payout asset and enough of the network's native asset for transaction fees.

---

Maintenance: rotation, regeneration, deletion

---

Troubleshooting

---

Questions or a step that doesn't match what you see? Contact your Toku account manager or support - we're happy to walk through the setup together.