Building for Flow (deposits & payments)

Flow is an enterprise feature. Contact us to enable it for your environment.

Prerequisites

Before this page: a connected wallet (see Connecting external wallets) for the wallet payment path. Your backend creates the flow and passes its flowId to the frontend — flow creation is server-side; this page covers the frontend.

What you’ll build

A Flow deposit takes a payment from a user’s wallet or an exchange and settles it to a destination. The frontend walks the flow through its lifecycle:

Load the flow and check it’s still actionable.
Attach a source — a wallet or an exchange.
Quote — lock in amounts and fees.
Sign & submit (wallet) or confirm (exchange).
Track to settlement.

The flow’s executionState and settlementState are string unions you branch on at every step.

Load the flow

Read flowId (typically from the URL so a user can resume) and load it with getFlow. Skip the UI when the flow has already reached a terminal state.

TypeScript
React

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

// 'broadcasted' and 'source_confirmed' are mid-flight, not terminal --
// the transaction landed on-chain but settlement can still be pending.
// This must match the same check used in "Track to settlement" below.
function isFlowFinished(flow: { executionState: string; settlementState: string }) {
  return (
    ['cancelled', 'expired', 'failed'].includes(flow.executionState) ||
    ['completed', 'failed'].includes(flow.settlementState)
  );
}

async function loadFlow(flowId: string) {
  const flow = await getFlow({ flowId });
  if (isFlowFinished(flow)) {
    showFinished(flow); // your implementation
    return null;
  }
  return flow;
}

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

function FlowScreen({ flowId }: { flowId: string }) {
  const { data: flow, isLoading } = useGetFlow({ flowId });

  if (isLoading) return <span>Loading…</span>;
  if (!flow) return null;

  // Branch on flow.executionState to pick which step to render.
  // FlowSteps is your implementation.
  return <FlowSteps flow={flow} />;
}

Attach a payment source

attachFlowSource records where the payment comes from. For a wallet, pass the user’s address and chain. For an exchange, pass the provider — the response’s flow carries the hosted buy URL to open.

TypeScript
React

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

async function attachWallet(flowId: string, walletAccount: WalletAccount) {
  await attachFlowSource({
    flowId,
    sourceType: 'wallet',
    fromAddress: walletAccount.address,
    fromChainName: walletAccount.chain,
  });
}

async function attachExchange(flowId: string) {
  const { flow } = await attachFlowSource({
    flowId,
    sourceType: 'exchange',
    exchangeProvider: 'coinbase',
  });
  return flow; // open the exchange buy URL from the flow's source metadata
}

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

function AttachWalletButton({
  flowId,
  walletAccount,
}: {
  flowId: string;
  walletAccount: WalletAccount;
}) {
  const { mutateAsync: attach, isPending } = useAttachFlowSource();

  const onClick = async () => {
    await attach({
      flowId,
      sourceType: 'wallet',
      fromAddress: walletAccount.address,
      fromChainName: walletAccount.chain,
    });
  };

  return (
    <button type="button" onClick={onClick} disabled={isPending}>
      Pay with wallet
    </button>
  );
}

Quote the flow

getFlowQuote returns the flow with a quote — fromAmount, toAmount, fees, and estimatedTimeSec. Quotes expire (quote.expiresAt), so let the user re-quote before signing. Omit fromTokenAddress to pay in the chain’s native token.

TypeScript
React

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

async function quote(flowId: string, fromTokenAddress?: string) {
  const flow = await getFlowQuote({ flowId, fromTokenAddress });
  if (!flow.quote) return;

  showQuote({
    send: flow.quote.fromAmount,
    receive: flow.quote.toAmount,
    feesUsd: flow.quote.fees?.totalFeeUsd,
    expiresAt: flow.quote.expiresAt,
  }); // your implementation
  return flow;
}

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

function QuoteButton({ flowId }: { flowId: string }) {
  const { mutateAsync: getQuote, data, isPending } = useGetFlowQuote();
  const quote = data?.quote;

  return (
    <div>
      <button type="button" onClick={() => getQuote({ flowId })} disabled={isPending}>
        {isPending ? 'Refreshing…' : 'Get quote'}
      </button>
      {quote && (
        <p>
          Send {quote.fromAmount} → receive {quote.toAmount}
        </p>
      )}
    </div>
  );
}

Sign and submit (wallet)

submitFlowTransaction runs the whole signing pipeline — prepare, approve (if the token needs an allowance), sign, and broadcast. onStepChange fires 'approval' then 'transaction' so you can show progress.

TypeScript
React

import { submitFlowTransaction, type WalletAccount } from '@dynamic-labs-sdk/client';

async function submit(flowId: string, walletAccount: WalletAccount) {
  const flow = await submitFlowTransaction({
    flowId,
    walletAccount,
    // updateStep is your implementation — 'approval' | 'transaction'.
    onStepChange: (step) => updateStep(step),
  });
  return flow;
}

import { type WalletAccount } from '@dynamic-labs-sdk/client';
import { useSubmitFlowTransaction } from '@dynamic-labs-sdk/react-hooks';

function SubmitButton({
  flowId,
  walletAccount,
}: {
  flowId: string;
  walletAccount: WalletAccount;
}) {
  const { mutateAsync: submit, isPending } = useSubmitFlowTransaction();

  const onClick = async () => {
    await submit({
      flowId,
      walletAccount,
      // updateStep is your implementation.
      onStepChange: (step) => updateStep(step),
    });
  };

  return (
    <button type="button" onClick={onClick} disabled={isPending}>
      Confirm & sign
    </button>
  );
}

For an exchange source, the user pays on the exchange instead of signing. Once they’re done, call broadcastFlow({ flowId }) to tell the backend the transfer was made.

Track to settlement

Poll getFlow until it settles. executionState covers the on-chain leg (broadcasted → source_confirmed); settlementState covers delivery (settling → completed). Stop when either terminates.

TypeScript
React

import { getFlow } from '@dynamic-labs-sdk/client';
import type { Flow } from '@dynamic-labs-sdk/client';

function isDone(flow: Flow) {
  return (
    ['cancelled', 'expired', 'failed'].includes(flow.executionState) ||
    ['completed', 'failed'].includes(flow.settlementState)
  );
}

async function poll(flowId: string) {
  const flow = await getFlow({ flowId });
  renderProgress(flow.executionState, flow.settlementState); // your implementation
  if (!isDone(flow)) setTimeout(() => poll(flowId), 3000);
}

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

function FlowStatus({ flowId }: { flowId: string }) {
  const { data: flow } = useGetFlow({
    flowId,
    queryParams: {
      refetchInterval: (query) => {
        const f = query.state.data;
        if (!f) return 3000;
        const done =
          ['cancelled', 'expired', 'failed'].includes(f.executionState) ||
          ['completed', 'failed'].includes(f.settlementState);
        return done ? false : 3000;
      },
    },
  });

  if (!flow) return null;
  if (flow.settlementState === 'completed') return <span>Payment complete</span>;
  if (flow.executionState === 'failed' || flow.settlementState === 'failed')
    return <span>Payment failed</span>;
  return <span>Processing…</span>;
}

Cancelling

Before broadcast, a user can back out with cancelFlow({ flowId }). After broadcast the transaction is on-chain and can’t be reversed — hide the cancel entry point once executionState reaches broadcasted.

Handling errors

Situation	What to do
Flow in a terminal state on load	Show a finished/expired screen instead of the payment UI.
Quote expired before signing	Re-quote with `getFlowQuote`, then let the user sign again.
User rejected the wallet prompt	No funds moved — keep the submit entry point to retry.
`settlementState === 'failed'`	Surface the failure; inspect `flow.failure` for context.

Installation & Configuration

React Native

Building UI

Chains & Networks

Authenticate

User & Session Management

Wallets

Flow

Swaps

Funding & Onramp

Events

Building for Flow (deposits & payments)

Prerequisites

What you’ll build

Load the flow

Attach a payment source

Quote the flow

Sign and submit (wallet)

Track to settlement

Cancelling

Handling errors

See also

​Prerequisites

​What you’ll build

​Load the flow

​Attach a payment source

​Quote the flow

​Sign and submit (wallet)

​Track to settlement

​Cancelling

​Handling errors

​See also

Prerequisites

What you’ll build

Load the flow

Attach a payment source

Quote the flow

Sign and submit (wallet)

Track to settlement

Cancelling

Handling errors

See also