attachFlowSource

attachFlowSource

Attaches a payment source to a flow. Supports three source types: wallet, exchange, and deposit_address. Returns the updated flow and a session token that authenticates all subsequent calls for this flow.

When to call

Call attachFlowSource only when executionState is initiated, source_attached, quoted, or signing. Re-attaching before broadcast lets the user change the source and rotates the flow session token.

Before restoring or retrying a flow, call getFlow and check its current state.

Do not call attachFlowSource after broadcasted or source_confirmed. Poll the existing flow instead. If the flow is cancelled, expired, or failed, create a new flow for another attempt. Reusing a confirmed flow returns 409 because source_confirmed → source_attached is not a valid execution-state transition.

Usage

import { attachFlowSource } from '@dynamic-labs-sdk/client';

const { flow, sessionToken } = await attachFlowSource({
  flowId: 'your-flow-id',
  fromAddress: '0xYourWalletAddress',
  fromChainId: '1',
  fromChainName: 'EVM',
  sourceType: 'wallet',
});

Parameters

This is a discriminated union on sourceType. The required and optional fields differ per source type.

Wallet source (sourceType: 'wallet')

User pays from a connected wallet. The source address is screened for sanctions.

Parameter	Type	Description
flowId	string	The flow ID.
sourceType	'wallet'	Indicates a wallet source.
fromAddress	string	The wallet address funding the flow.
fromChainName	Chain	Chain family: 'EVM', 'SOL', 'BTC', 'SUI', 'TRON'.
fromChainId	string	Network ID (e.g., '1' for Ethereum, '8453' for Base).

Exchange source (sourceType: 'exchange')

User pays from a CEX balance (e.g. Coinbase). The response includes an exchange buy URL to redirect the user to. No sanctions screening: the exchange KYCs the funder.

Parameter	Type	Description
flowId	string	The flow ID.
sourceType	'exchange'	Indicates an exchange source.
exchangeProvider	'coinbase'	The exchange provider.

Deposit address source (sourceType: 'deposit_address')

A unique deposit address is generated for the flow. The user sends funds directly to it: no wallet connection required. Works for BTC, SOL, EVM, and TRON. Call getFlowQuote after attaching to get the depositAddress, which you can display as a QR code or copy string.

Parameter	Type	Description
flowId	string	The flow ID.
sourceType	'deposit_address'	Indicates a deposit address source.
fromChainName	Chain	Chain family the user will send from: 'EVM', 'SOL', 'BTC', 'TRON'.
fromChainId	string	Network ID for the origin chain (e.g., '1' for BTC, '101' for SOL, '8453' for Base).
refundAddress	string	Where to return funds if the transfer fails.

Do not pass fromAddress with sourceType: 'deposit_address': the API returns 400.

Returns

Promise<FlowSourceResponse>:

import type { Flow } from '@dynamic-labs-sdk/client';
type FlowSourceResponse = {
  flow: Flow;
  sessionToken: string;
  sessionExpiresAt: string; // ISO 8601 — when the session token expires
};

Examples

Wallet source (EVM)

import { attachFlowSource } from '@dynamic-labs-sdk/client';

const { flow } = await attachFlowSource({
  flowId: 'your-flow-id',
  fromAddress: '0xYourWalletAddress',
  fromChainId: '8453',
  fromChainName: 'EVM',
  sourceType: 'wallet',
});

Wallet source (Solana)

import { attachFlowSource } from '@dynamic-labs-sdk/client';

const { flow } = await attachFlowSource({
  flowId: 'your-flow-id',
  fromAddress: 'YourSolanaAddress',
  fromChainId: '101',
  fromChainName: 'SOL',
  sourceType: 'wallet',
});

Exchange source (Coinbase)

import { attachFlowSource } from '@dynamic-labs-sdk/client';

const { flow } = await attachFlowSource({
  flowId: 'your-flow-id',
  sourceType: 'exchange',
  exchangeProvider: 'coinbase',
});

// metadata's shape is provider-specific, so cast to read the exchange buy URL.
const exchangeUrl = (flow.exchangeSource?.metadata as { url?: string })?.url;

Deposit address source

No wallet connection or signing required. After attaching the source, call getFlowQuote to get the deposit address to show the user.

import { attachFlowSource, getFlowQuote } from '@dynamic-labs-sdk/client';

await attachFlowSource({
  flowId: 'your-flow-id',
  sourceType: 'deposit_address',
  fromChainId: '1',
  fromChainName: 'BTC',
  refundAddress: 'bc1q...', // where to return funds if the transfer fails
});

const quoted = await getFlowQuote({ flowId: 'your-flow-id' });
const depositAddress = quoted.depositAddress;
// Show depositAddress to the user — they send funds to it from any wallet or exchange

React

import { useAttachFlowSource } from '@dynamic-labs-sdk/react-hooks';

function AttachWallet({ flowId, walletAccount }) {
  const { mutate: attachSource, isPending } = useAttachFlowSource();

  return (
    <button
      onClick={() =>
        attachSource({
          flowId,
          fromAddress: walletAccount.address,
          fromChainId: '1',
          fromChainName: 'EVM',
          sourceType: 'wallet',
        })
      }
      disabled={isPending}
    >
      {isPending ? 'Attaching...' : 'Pay with wallet'}
    </button>
  );
}

Related

• Fireblocks Flow JavaScript SDK guide: End-to-end flow guide including deposit address
• Fireblocks Flow API guide: Deposit address flow (raw HTTP)
• getFlowQuote: Get a conversion quote (returns depositAddress for deposit address sources)
• submitFlowTransaction: Submit for signing and broadcast (wallet sources only)
• cancelFlow: Cancel a flow