> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](/docs/javascript/reference/client/get-flow) and check its current state.

<Warning>
  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.
</Warning>

## Usage

```javascript theme={"system"}
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, and EVM. 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'`.                             |
| `fromChainId`   | `string`            | Network ID for the origin chain (e.g., `'1'` for BTC, `'101'` for SOL, `'8453'` for Base).   |
| `refundAddress` | `string` (optional) | Where to return funds if the transfer fails. Omit to refund to the original sending address. |

<Warning>
  Do not pass `fromAddress` with `sourceType: 'deposit_address'` — the API returns `400`.
</Warning>

## Returns

`Promise<FlowSourceResponse>`:

```typescript theme={"system"}
type FlowSourceResponse = {
  flow: Flow;
  sessionToken: string;
  sessionExpiresAt: string; // ISO 8601 — when the session token expires
};
```

## Examples

### Wallet source (EVM)

```javascript theme={"system"}
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)

```javascript theme={"system"}
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)

```javascript theme={"system"}
import { attachFlowSource } from '@dynamic-labs-sdk/client';

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

// Open the exchange buy URL for the user
const exchangeUrl = flow.exchangeSource?.metadata?.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.

```javascript theme={"system"}
import { attachFlowSource, getFlowQuote } from '@dynamic-labs-sdk/client';

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

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

## React

```tsx theme={"system"}
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](/docs/overview/fireblocks-flow-js-sdk) — End-to-end flow guide including deposit address
* [Fireblocks Flow API guide](/docs/overview/fireblocks-flow-api#deposit-address-flow) — Deposit address flow (raw HTTP)
* [`getFlowQuote`](/docs/javascript/reference/client/get-flow-quote) — Get a conversion quote (returns `depositAddress` for deposit address sources)
* [`submitFlowTransaction`](/docs/javascript/reference/client/submit-flow-transaction) — Submit for signing and broadcast (wallet sources only)
* [`cancelFlow`](/docs/javascript/reference/client/cancel-flow) — Cancel a flow