Get started with Flow payments

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

This guide sets up the JavaScript SDK for Flow payments and walks through a first payment from a connected wallet. Your server creates the flow, and the payer’s page uses the SDK to attach a source, get a quote, and send the payment. The same setup covers every mode: payment, deposit, and withdraw.

Prerequisites

A Dynamic environment with Fireblocks Flow enabled.
A Dynamic client created and initialized, as described in Creating a Dynamic client.
A server that can call the Dynamic API. Your API token stays on that server.

Enable chains in the Dynamic Console

Open Chains & Networks in the Dynamic Console and enable every chain your payers will pay from. Wallet payments support these chains:

Chain	Console toggle	Extension package
EVM (Ethereum, Base, Polygon, Arbitrum, etc.)	EVM	`@dynamic-labs-sdk/evm`
Solana	Solana	`@dynamic-labs-sdk/solana`
Bitcoin	Bitcoin	`@dynamic-labs-sdk/bitcoin`
Sui	Sui	`@dynamic-labs-sdk/sui`
TRON	Tron	`@dynamic-labs-sdk/tron`

Each chain you enable appears when the payer connects a wallet. Deposit-address and exchange payments do not need a chain extension, because the payer pays outside your app. Supported chains lists the chains each payment source supports.

Install chain extensions

Install the packages for the chains you enabled:

npm install @dynamic-labs-sdk/evm @dynamic-labs-sdk/solana @dynamic-labs-sdk/bitcoin @dynamic-labs-sdk/sui @dynamic-labs-sdk/tron

Then add an extension for each chain when you create the client. Extensions register the wallet providers the SDK uses to find, connect, and sign with wallets on that chain.

import { createDynamicClient, initializeClient } from "@dynamic-labs-sdk/client";
import { addBitcoinExtension } from "@dynamic-labs-sdk/bitcoin";
import { addEvmExtension } from "@dynamic-labs-sdk/evm";
import { addWalletConnectEvmExtension } from "@dynamic-labs-sdk/evm/wallet-connect";
import { addSolanaExtension } from "@dynamic-labs-sdk/solana";
import { addWalletConnectSolanaExtension } from "@dynamic-labs-sdk/solana/wallet-connect";
import { addSuiExtension } from "@dynamic-labs-sdk/sui";
import { addTronExtension } from "@dynamic-labs-sdk/tron";

createDynamicClient({
  environmentId: "<YOUR_ENVIRONMENT_ID>",
});

// Add one extension per chain you enabled
addEvmExtension();
addSolanaExtension();
addBitcoinExtension();
addSuiExtension();
addTronExtension();

// Optional: let payers connect mobile wallets with a QR code
addWalletConnectEvmExtension();
addWalletConnectSolanaExtension();

initializeClient();

Add extensions only for the chains you enabled. The WalletConnect extensions are optional, and they let payers connect mobile wallets such as MetaMask Mobile or Phantom by scanning a QR code. Adding extensions lists every extension.

Create an API token

In the Dynamic Console, go to Developer > API Tokens and create a token with the flow.write scope. Your server uses it to create flows, and also to read and cancel them from the server and to manage fees. Keep the token on your server and read it from an environment variable or a secrets manager. The payer’s page never needs it: reading a flow and attaching a source need no credential, and attaching a source returns a session token that the SDK stores and sends for the rest of the payment. Access and data explains each credential.

Create a flow from your server

Your server creates the flow and fixes its mode, amount, currency, settlement tokens, and destinations. The mode goes in the path. This example creates a payment flow for 25 USD that settles in USDC on Base, and reads the API token and environment ID from environment variables:

curl --request POST \
  --url "https://app.dynamic.xyz/api/v0/server/$DYNAMIC_ENVIRONMENT_ID/flow/payment" \
  --header "Authorization: Bearer $DYNAMIC_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": "25.00",
    "currency": "USD",
    "settlementConfig": {
      "strategy": "cheapest",
      "settlements": [
        {
          "chainName": "EVM",
          "chainId": "8453",
          "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "symbol": "USDC",
          "tokenDecimals": 6
        }
      ]
    },
    "destinationConfig": {
      "destinations": [
        { "chainName": "EVM", "type": "address", "identifier": "0xYourEvmDestinationAddress" }
      ]
    },
    "memo": { "orderId": "order_abc123" }
  }'

The response wraps the new flow in flow. Pass flow.id to the payer’s page, where the SDK functions take it as flowId. Share the flow ID only with the payer, because it is enough to read the flow and to attach a source before the payment is sent. The modes differ in who sets the amount:

Mode	Amount
`payment`	Fixed when you create the flow, in `USD` or in `SETTLEMENT_TOKEN` when the flow has exactly one settlement token.
`deposit`	A suggestion. The payer can change it when they get a quote, as shown in Deposit mode amount entry.
`withdraw`	Fixed in `USD`. Your platform pays out to the user and signs with its own wallet.

The Flow payments API guide lists every field of the create request.

Optional: add your own fee. Add a feeConfig to the create request to take a percentage of the payment for yourself or for your own customers. Recipients can be EVM or Solana addresses, with at most one recipient per address family. The fee applies to deposit-address payments and to wallet payments that need a swap. Direct wallet transfers and exchange payments carry no fee. Adding your own fee explains when the fee applies, and the Fees API gives the config shape and how to claim fees.

Optional: require an exact match. Add disableSwaps: true when the payer must pay with a token and chain that already match one of your settlements. See Conversions.

Send a first payment

On the payer’s page, connect a wallet with your usual wallet connection UI, then attach it to the flow, get a quote, and send the payment with submitFlowTransaction. submitFlowTransaction prepares the transaction, asks the wallet to sign and send it, and reports it to the flow.

import {
  attachFlowSource,
  getActiveNetworkId,
  getFlow,
  getFlowQuote,
  shouldPollFlow,
  submitFlowTransaction,
} from "@dynamic-labs-sdk/client";

const POLL_INTERVAL_MS = 3000;

const payWithWallet = async ({ flowId, walletAccount, fromTokenAddress }) => {
  // 1. Attach the connected wallet as the payment source
  const { networkId } = await getActiveNetworkId({ walletAccount });
  await attachFlowSource({
    flowId,
    sourceType: "wallet",
    fromAddress: walletAccount.address,
    fromChainName: walletAccount.chain,
    fromChainId: networkId,
  });

  // 2. Quote the token the payer chose; the quote is valid for 60 seconds
  const quoted = await getFlowQuote({ flowId, fromChainId: networkId, fromTokenAddress });
  // Show quoted.quote to the payer here and wait for them to confirm

  // 3. Prepare, sign, and report the transaction in one call
  let flow = await submitFlowTransaction({ flowId, walletAccount });

  // 4. Read the flow until it stops changing on its own
  while (shouldPollFlow({ flow })) {
    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
    flow = await getFlow({ flowId });
  }

  return flow;
};

The payment is done when flow.settlementState is completed. A flow whose executionState is source_confirmed has received the payer’s funds but has not finished delivering them, so keep reading it until settlement completes or fails. Payment lifecycle and states describes every state. Decide fulfillment on your server, from webhooks or a server read of the flow, rather than from what the payer’s page reports. Access and data explains why.

Next steps

Build a custom payment UI

Every payment source, quote refresh, errors, cancel, expiry, and reload.

Handle Flow errors

The error classes each function throws and how to recover.

Flow payments

Modes, payment sources, and how you know a payment worked.

Flow payments API guide

The HTTP requests behind each SDK function.

Learn

Implement

Get started with Flow payments

Prerequisites

Enable chains in the Dynamic Console

Install chain extensions

Create an API token

Create a flow from your server

Send a first payment

Next steps

Build a custom payment UI

Handle Flow errors

Flow payments

Flow payments API guide

​Prerequisites

​Enable chains in the Dynamic Console

​Install chain extensions

​Create an API token

​Create a flow from your server

​Send a first payment

​Next steps

Build a custom payment UI

Handle Flow errors

Flow payments

Flow payments API guide

Prerequisites

Enable chains in the Dynamic Console

Install chain extensions

Create an API token

Create a flow from your server

Send a first payment

Next steps