Fees API

This is an enterprise-only feature. Please contact us to enable.

You can add your own fee to a Flow payment: a percentage of the source amount, paid to wallets you name. Your server attaches a fee config when it creates the flow. The recipient does not have to be you; for example, a platform can pay the fee to its own merchants. Adding your own fee explains the concept, and this page gives the requests. The fee is collected by the provider that routes the payment, so it applies to these payments:

Deposit-address payments, whether or not the payment needs a conversion.
Wallet payments that need a swap, because the payer’s token or chain differs from your settlement.

Direct wallet transfers, where the payer already holds a settlement token on a settlement chain, and exchange payments carry no added fee. A flow with disableSwaps collects the fee on deposit-address payments only, because every wallet payment in that flow is a direct transfer. Depending on the provider, a fee reaches the recipient in one of two ways:

Paid on chain with the payment. The fee goes to the recipient’s wallet as part of the payment, and there is nothing to claim.
Accrued as a claimable balance. The fee accumulates off chain, typically as USDC, and the recipient claims it later with the claim requests. Claims are available for EVM recipients.

An integration that adds fees should handle both: check claimable balances periodically and claim what is waiting.

Add a fee config

feeConfig is an optional field on the create request in every mode, and on payment links. It is fixed when the flow is created.

{
  "amount": "25.00",
  "currency": "USD",
  "settlementConfig": { "...": "..." },
  "destinationConfig": { "...": "..." },
  "feeConfig": {
    "recipients": [
      {
        "walletAddress": "0xYourFeeRecipientWallet",
        "percentage": 0.01
      }
    ]
  }
}

Field	Description
`feeConfig.recipients`	One or two recipients, with at most one EVM address and at most one Solana address
`feeConfig.recipients[].walletAddress`	The wallet that receives the fee and, for claims, signs to release it. A valid EVM (`0x…`) or Solana (base58) address
`feeConfig.recipients[].percentage`	The share of the source amount to collect, as a decimal strictly between `0` and `1`. For example, `0.01` is 1%

The create request returns 422 when:

there are no recipients, or more than one recipient in the same address family (EVM or Solana),
a percentage is not strictly between 0 and 1,
the recipients’ percentages add up to 1 or more, or
a walletAddress is not a valid EVM or Solana address.

Each recipient’s share is its percentage of the source amount, calculated independently.

Supported chains for fees

A provider can pay a recipient only on the chain families it supports for a given payment, and it skips a recipient it cannot pay. The fee is not always paid on the chain the payer paid from: a payment that started on Solana can pay your fee to an EVM address. Name both an EVM and a Solana recipient to give each payment the best chance of carrying the fee:

"feeConfig": {
  "recipients": [
    {
      "walletAddress": "0xYourFeeRecipientWallet",
      "percentage": 0.01
    },
    {
      "walletAddress": "YourSolanaFeeRecipientWallet",
      "percentage": 0.01
    }
  ]
}

Use the same percentage for both. A payment pays only one of them, so your fee rate stays the same. Some payments carry no fee even with both recipients named, for example a deposit-address payment that starts and settles on Solana. The payer can pay from any supported chain. Fees to a Solana recipient arrive on chain with the payment. Fees that accrue to an EVM recipient are collected with the claim requests below.

Check claimable balances

Check whether a recipient has fees waiting to be claimed. The response lists the balance per token and chain, and hasClaimableFees says whether anything is waiting. Paths are relative to https://app.dynamic.xyz/api/v0, and every fee request uses your API token with flow.write.

GET /server/{environmentId}/flow/fees/balances?recipientAddress=0xYourFeeRecipientWallet
Authorization: Bearer $DYNAMIC_API_TOKEN

Query param	Description
`recipientAddress`	Required. The fee recipient’s EVM wallet address
`chainId`	Optional filter. Only return balances settled on this chain
`tokenAddress`	Optional filter. Only return balances for this token contract address

Response (200):

{
  "balances": [
    {
      "amount": "75021651210714015",
      "chainId": "8453",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amountUSD": "116.235557",
      "tokenSymbol": "USDC"
    }
  ],
  "hasClaimableFees": true
}

Field	Description
`balances`	One entry per claimable token/chain balance. Empty when there is nothing to claim
`balances[].amount`	Claimable amount as a string in the token’s smallest unit
`balances[].chainId`	Chain the balance can be claimed and settled on
`balances[].tokenAddress`	Token contract address the balance is denominated in
`balances[].amountUSD`	Approximate USD value, when available
`balances[].tokenSymbol`	Human-readable token symbol, when available
`hasClaimableFees`	`true` when there is at least one claimable balance

An empty balances list (hasClaimableFees: false) means there is nothing to claim right now. Either no fees have accrued, or every fee was paid on chain with its payment.

Error (400): recipientAddress is not a valid EVM address.

Claim accrued fees

A claim takes two requests. The first returns the messages the recipient wallet must sign, and the second submits the signatures. The recipient wallet’s signature authorizes the release. 1. Initiate the claim.

POST /server/{environmentId}/flow/fees/claim
Authorization: Bearer $DYNAMIC_API_TOKEN
Content-Type: application/json

{
  "recipientAddress": "0xYourFeeRecipientWallet"
}

Field	Description
`recipientAddress`	Required. The fee recipient’s EVM wallet address
`chainId`	Optional filter. Only claim balances settled on this chain
`tokenAddress`	Optional filter. Only claim balances for this token contract address

Response (200):

{
  "requestId": "e2b1c3d4-5678-90ab-cdef-1234567890ab",
  "steps": [
    {
      "id": "step-1",
      "type": "signature",
      "data": {
        "message": "0x0747b5e4d6cab0e29ad37654c41c2556524b85e0114ca2d61c76375bc98fb3a4",
        "signatureKind": "eip191"
      }
    }
  ]
}

Field	Description
`requestId`	Identifier that ties the submit request to this claim. Store it
`steps`	One step per claimable balance. Each is a payload the recipient wallet must sign
`steps[].id`	Step identifier, echoed back as `stepId` when you submit its signature
`steps[].type`	The step type. `signature` is a message the recipient wallet must sign
`steps[].data.message`	The exact message to sign. Sign it as-is; do not reconstruct or modify it
`steps[].data.signatureKind`	How to sign the message. `eip191` is a `personal_sign` message

An empty steps array means there was nothing to claim, so there is nothing to sign or submit. Error (400): recipientAddress is not a valid EVM address. 2. Sign each step with the recipient wallet, then submit the signatures.

POST /server/{environmentId}/flow/fees/claim/submit
Authorization: Bearer $DYNAMIC_API_TOKEN
Content-Type: application/json

{
  "requestId": "e2b1c3d4-5678-90ab-cdef-1234567890ab",
  "signatures": [
    {
      "stepId": "step-1",
      "signature": "0xRecipientSignatureOverStep1Payload"
    }
  ]
}

Field	Description
`requestId`	The `requestId` returned when you initiated the claim
`signatures`	One signature per step returned by initiate
`signatures[].stepId`	The `id` of the step this signature is for
`signatures[].signature`	The recipient’s signature over that step’s payload

Response (200):

{
  "status": "DONE"
}

Field	Description
`status`	The outcome of the claim: `DONE`, `PENDING`, or `FAILED`
`txHashes`	The on-chain transaction hashes of claims that settled on chain

After a successful submit, check balances again. The claimed balance should now be empty.

Example: claim in TypeScript

claim-fees.ts

import { type WalletClient } from 'viem';

const API = 'https://app.dynamic.xyz/api/v0';
const ENV_ID = process.env.DYNAMIC_ENVIRONMENT_ID!;
const API_TOKEN = process.env.DYNAMIC_API_TOKEN!; // needs flow.write

// 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 the claim and 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`, which viem's signMessage produces.
  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();
};

Sign data.message exactly as returned, without reconstructing or changing it. data.signatureKind is eip191, a standard personal-sign message, so a library’s signMessage, such as viem’s, produces the right signature.

Learn

Implement

Add a fee config

Supported chains for fees

Check claimable balances

Claim accrued fees

Example: claim in TypeScript

​Add a fee config

​Supported chains for fees

​Check claimable balances

​Claim accrued fees

​Example: claim in TypeScript

Add a fee config

Supported chains for fees

Check claimable balances

Claim accrued fees

Example: claim in TypeScript