Fireblocks Flow API guide

{
  "eventId": "...",
  "eventName": "flow.settlement.updated",
  "environmentId": "...",
  "environmentName": "live",
  "timestamp": "2026-06-15T12:00:00.000Z",
  "data": {
    "axis": "settlement",
    "flowId": "fl_abc123",
    "previousState": "settling",
    "newState": "completed",
    "timestamp": "2026-06-15T12:00:00.000Z"
  }
}

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/flow', (req, res) => {
  const { eventName, data } = req.body;

  if (
    eventName === 'flow.settlement.updated' &&
    data.newState === 'completed'
  ) {
    fulfillOrder(data.flowId);
  }

  if (data.newState === 'failed') {
    handleFailure(data.flowId, eventName, data.previousState);
  }

  // Respond quickly — process async
  res.sendStatus(200);
});

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/flow', (req, res) => {
  const { eventName, data } = req.body;

  if (
    eventName === 'flow.settlement.updated' &&
    data.newState === 'completed'
  ) {
    creditUserAccount(data.flowId);
  }

  if (data.newState === 'failed') {
    handleFailure(data.flowId, eventName, data.previousState);
  }

  // Respond quickly — process async
  res.sendStatus(200);
});

import { parseAbi } from 'viem';

const { signingPayload } = prepared.quote;

// Handle ERC-20 approval if needed
if (signingPayload.evmApproval) {
  const { tokenAddress, spenderAddress, amount } = signingPayload.evmApproval;
  const approvalHash = await walletClient.writeContract({
    address: tokenAddress as `0x${string}`,
    abi: parseAbi(['function approve(address, uint256) returns (bool)']),
    functionName: 'approve',
    args: [spenderAddress as `0x${string}`, BigInt(amount)],
  });
  await walletClient.waitForTransactionReceipt({ hash: approvalHash });
}

// Send the main transaction
const txHash = await walletClient.sendTransaction({
  to: signingPayload.evmTransaction.to as `0x${string}`,
  data: signingPayload.evmTransaction.data as `0x${string}`,
  value: BigInt(signingPayload.evmTransaction.value),
});

import { DynamicEvmWalletClient } from '@dynamic-labs-wallet/node-evm';

const client = new DynamicEvmWalletClient({ environmentId });
await client.authenticateApiToken(apiToken);

const walletClient = await client.getWalletClient({
  accountAddress,
  chainId: 8453, // Base
  rpcUrl: 'https://mainnet.base.org',
});

const { evmTransaction: tx, evmApproval } = prepared.quote.signingPayload;

if (evmApproval) {
  // send approval tx first (see browser example above for ABI)
}

const txHash = await walletClient.sendTransaction({
  to:    tx.to as `0x${string}`,
  data:  tx.data as `0x${string}`,
  value: BigInt(tx.value || '0'),
  gas:   tx.gasLimit ? BigInt(tx.gasLimit) : undefined,
  chainId: 8453,
});

import {
  Connection,
  Keypair,
  VersionedTransaction,
} from '@solana/web3.js';

const connection = new Connection(
  process.env.SOLANA_RPC_URL ?? 'https://api.mainnet-beta.solana.com',
  'confirmed'
);
const signer = Keypair.fromSecretKey(
  Uint8Array.from(JSON.parse(process.env.SOLANA_SECRET_KEY as string))
);

const tx = VersionedTransaction.deserialize(
  Buffer.from(prepared.quote.signingPayload.serializedTransaction, 'base64')
);
tx.sign([signer]);

const txHash = await connection.sendRawTransaction(tx.serialize());
await connection.confirmTransaction(txHash, 'confirmed');

import { DynamicSvmWalletClient, decodeBase58, addSignatureToTransaction } from '@dynamic-labs-wallet/node-svm';
import { VersionedTransaction, Connection, PublicKey } from '@solana/web3.js';

const client = new DynamicSvmWalletClient({ environmentId });
await client.authenticateApiToken(apiToken);

// Decode the base64 payload from prepare → VersionedTransaction
const vtx = VersionedTransaction.deserialize(
  Buffer.from(prepared.quote.signingPayload.serializedTransaction, 'base64')
);

// Sign — returns base58 signature (64 bytes), NOT the full signed tx
const signatureBase58 = await client.signTransaction({
  walletMetadata,
  transaction: vtx,
});

// Decode signature and add it back to the transaction
const sigBytes = decodeBase58(signatureBase58);
const signedVtx = addSignatureToTransaction({
  transaction: vtx,
  signature: sigBytes,
  signerPublicKey: new PublicKey(accountAddress),
});

// Broadcast — skipPreflight avoids false failures from stale oracle simulations
const connection = new Connection(
  process.env.SOLANA_RPC_URL ?? 'https://api.mainnet-beta.solana.com',
  'confirmed'
);
const txHash = await connection.sendRawTransaction(signedVtx.serialize(), {
  skipPreflight: true,
});
await connection.confirmTransaction(txHash, 'confirmed');

import { type WalletClient } from 'viem';

const API = 'https://app.dynamicauth.com/api/v0';
const ENV_ID = 'your-environment-id';
const API_TOKEN = 'dyn_your_api_token'; // must have flow.write scope

// The recipient wallet from feeConfig — it signs to authorize the claim.
declare const wallet: WalletClient;

const claimFees = async (recipientAddress: `0x${string}`) => {
  const headers = {
    Authorization: `Bearer ${API_TOKEN}`,
    'Content-Type': 'application/json',
  };

  // 1. Is there anything to claim?
  const balancesRes = await fetch(
    `${API}/server/${ENV_ID}/flow/fees/balances?recipientAddress=${recipientAddress}`,
    { headers },
  );
  const { hasClaimableFees } = await balancesRes.json();
  if (!hasClaimableFees) {
    return;
  }

  // 2. Initiate — get the steps to sign.
  const initRes = await fetch(`${API}/server/${ENV_ID}/flow/fees/claim`, {
    body: JSON.stringify({ recipientAddress }),
    headers,
    method: 'POST',
  });
  const { requestId, steps } = await initRes.json();

  // 3. Sign each step's message with the recipient wallet.
  // data.signatureKind is `eip191` — viem's signMessage produces exactly that.
  const signatures = await Promise.all(
    steps.map(async (step: { data: { message: string }; id: string }) => ({
      signature: await wallet.signMessage({
        account: recipientAddress,
        message: step.data.message,
      }),
      stepId: step.id,
    })),
  );

  // 4. Submit the signatures.
  const submitRes = await fetch(
    `${API}/server/${ENV_ID}/flow/fees/claim/submit`,
    {
      body: JSON.stringify({ requestId, signatures }),
      headers,
      method: 'POST',
    },
  );

  return submitRes.json();
};

import { parseAbi, type WalletClient } from 'viem';

// --- Config ---
const API = 'https://app.dynamicauth.com/api/v0';
const ENV_ID = 'your-environment-id';
const API_TOKEN = 'dyn_your_api_token'; // must have flow.write scope

// Bring your own connected wallet client (viem, wagmi, Dynamic primary wallet, etc.)
declare const walletClient: WalletClient & {
  waitForTransactionReceipt: (args: { hash: `0x${string}` }) => Promise<unknown>;
};
const account = walletClient.account!;

// --- Helpers ---
async function api(path: string, options: RequestInit = {}) {
  const res = await fetch(`${API}${path}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });
  if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
  return res.json();
}

// --- Step 1: Create flow (server-side) ---
async function createFlow(amount: string): Promise<string> {
  const { flow } = await api(`/server/${ENV_ID}/flow/payment`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${API_TOKEN}` },
    body: JSON.stringify({
      amount,
      currency: 'USD',
      settlementConfig: {
        strategy: 'cheapest',
        settlements: [
          {
            chainName: 'EVM',
            chainId: '8453',
            symbol: 'USDC',
            tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
            tokenDecimals: 6,
          },
        ],
      },
      destinationConfig: {
        destinations: [
          {
            chainName: 'EVM',
            type: 'address',
            identifier: '0xYourDestinationWallet',
          },
        ],
      },
      memo: { orderId: 'order_abc123' },
    }),
  });
  console.log('Flow created:', flow.id);
  return flow.id;
}

// --- Steps 2–7: Client-side flow lifecycle ---
async function executeFlow(flowId: string) {
  // Step 2: Attach source (returns session token)
  const { sessionToken } = await api(`/sdk/${ENV_ID}/flow/${flowId}/source`, {
    method: 'POST',
    body: JSON.stringify({
      sourceType: 'wallet',
      fromAddress: account.address,
      fromChainId: '8453',
      fromChainName: 'EVM',
    }),
  });
  const session = { 'X-Dynamic-Flow-Session-Token': sessionToken };

  // Step 3: Get quote (paying with USDC on Base)
  const quoted = await api(`/sdk/${ENV_ID}/flow/${flowId}/quote`, {
    method: 'POST',
    headers: session,
    body: JSON.stringify({
      fromTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    }),
  });
  console.log(
    `Quote: send ${quoted.quote.fromAmount}, receive ${quoted.quote.toAmount}, fees: $${quoted.quote.fees?.totalFeeUsd}`
  );

  // Step 4: Prepare signing (with balance checks)
  const prepared = await api(`/sdk/${ENV_ID}/flow/${flowId}/prepare`, {
    method: 'POST',
    headers: session,
    body: JSON.stringify({
      assertBalanceForGasCost: true,
      assertBalanceForTransferAmount: true,
    }),
  });

  // Step 5: Sign and broadcast
  const { signingPayload } = prepared.quote;

  if (signingPayload.evmApproval) {
    const approvalHash = await walletClient.writeContract({
      address: signingPayload.evmApproval.tokenAddress as `0x${string}`,
      abi: parseAbi(['function approve(address, uint256) returns (bool)']),
      functionName: 'approve',
      args: [
        signingPayload.evmApproval.spenderAddress as `0x${string}`,
        BigInt(signingPayload.evmApproval.amount),
      ],
    });
    await walletClient.waitForTransactionReceipt({ hash: approvalHash });
    console.log('Token approved');
  }

  const txHash = await walletClient.sendTransaction({
    to: signingPayload.evmTransaction.to as `0x${string}`,
    data: signingPayload.evmTransaction.data as `0x${string}`,
    value: BigInt(signingPayload.evmTransaction.value),
  });
  console.log('Broadcasted:', txHash);

  // Step 6: Record broadcast
  await api(`/sdk/${ENV_ID}/flow/${flowId}/broadcast`, {
    method: 'POST',
    headers: session,
    body: JSON.stringify({ txHash }),
  });

  // Step 7: Poll for settlement
  while (true) {
    const flow = await api(`/sdk/${ENV_ID}/flow/${flowId}`);

    if (flow.settlementState === 'completed') {
      console.log('Payment settled!');
      return flow;
    }

    if (
      flow.settlementState === 'failed' ||
      ['cancelled', 'expired', 'failed'].includes(flow.executionState)
    ) {
      throw new Error(
        `Payment failed: execution=${flow.executionState}, settlement=${flow.settlementState}`
      );
    }

    console.log(
      `Waiting... execution=${flow.executionState}, settlement=${flow.settlementState}`
    );
    await new Promise((r) => setTimeout(r, 3000));
  }
}

// --- Run ---
const flowId = await createFlow('25.00');
await executeFlow(flowId);