Create transfers via API

This guide covers how to create transfers, handle different asset types, and monitor transfer status using the DFNS API and SDK.

Prerequisites

Service account or authenticated user with Wallets:Transfers:Create permission
DFNS SDK installed and configured
Wallet with sufficient balance for the transfer and gas fees

Creating a native token transfer

Send native tokens (ETH, MATIC, SOL, etc.):

import { DfnsApiClient } from '@dfns/sdk'

const dfns = new DfnsApiClient({
  baseUrl: 'https://api.dfns.io',
  // Your signer configuration
})

const transfer = await dfns.wallets.createTransfer({
  walletId: 'wa-xxx-xxx',
  body: {
    kind: 'Native',
    to: '0x1234...recipient',
    amount: '1000000000000000000' // 1 ETH in wei
  }
})

console.log('Transfer ID:', transfer.id)
console.log('Status:', transfer.status)

import (
    dfns "github.com/dfns/dfns-sdk-go/v2"
)

// client, _ := dfns.NewClient(dfns.Options{...})

transfer, err := client.Wallets.TransferAsset(ctx, "wa-xxx-xxx", map[string]any{
    "kind":   "Native",
    "to":     "0x1234...recipient",
    "amount": "1000000000000000000", // 1 ETH in wei
})

fmt.Printf("Transfer ID: %s\n", transfer.ID)
fmt.Printf("Status: %s\n", transfer.Status)

from dfns_sdk import DfnsClient, DfnsClientConfig

# config = DfnsClientConfig(auth_token="...", signer=signer)

with DfnsClient(config) as client:
    transfer = client.wallets.transfer_asset(
        "wa-xxx-xxx",
        body={
            "kind": "Native",
            "to": "0x1234...recipient",
            "amount": "1000000000000000000"  # 1 ETH in wei
        }
    )

    print(f"Transfer ID: {transfer['id']}")
    print(f"Status: {transfer['status']}")

import co.dfns.sdk.*;

// DfnsClient client = new DfnsClient(config);

var transfer = client.wallets.transferAsset("wa-xxx-xxx", java.util.Map.of(
    "kind", "Native",
    "to", "0x1234...recipient",
    "amount", "1000000000000000000" // 1 ETH in wei
));

System.out.printf("Transfer ID: %s%n", transfer.id());
System.out.printf("Status: %s%n", transfer.status());

Request parameters

Parameter	Required	Description
`kind`	Yes	Transfer type: `Native`, `Erc20`, `Erc721`, etc.
`to`	Yes	Recipient address
`amount`	Yes	Amount in base units (wei for ETH)
`externalId`	No	Your reference ID for tracking

There is no network parameter — the network is inherited from the wallet (walletId) the transfer is created on.

Creating an ERC-20 token transfer

Send ERC-20 tokens:

const transfer = await dfns.wallets.createTransfer({
  walletId: 'wa-xxx-xxx',
  body: {
    kind: 'Erc20',
    contract: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
    to: '0x1234...recipient',
    amount: '1000000' // 1 USDC (6 decimals)
  }
})

Token amounts are in base units. USDC has 6 decimals, so 1 USDC = 1000000. ETH has 18 decimals, so 1 ETH = 1000000000000000000.

Creating an NFT transfer

Transfer ERC-721 NFTs:

const transfer = await dfns.wallets.createTransfer({
  walletId: 'wa-xxx-xxx',
  body: {
    kind: 'Erc721',
    contract: '0x...nft-contract',
    to: '0x1234...recipient',
    tokenId: '123'
  }
})

Transfer with external ID

Use external IDs for your own tracking:

const transfer = await dfns.wallets.createTransfer({
  walletId: 'wa-xxx-xxx',
  body: {
    kind: 'Native',
    to: '0x1234...recipient',
    amount: '1000000000000000000',
    externalId: 'payout-2024-001' // Your reference
  }
})

Checking transfer status

Get the status of a transfer:

const transfer = await dfns.wallets.getTransfer({
  walletId: 'wa-xxx-xxx',
  transferId: 'tr-xxx-xxx'
})

console.log('Status:', transfer.status)
// 'Pending', 'Executing', 'Broadcasted', 'Confirmed', 'Failed', 'Rejected'

Transfer statuses

Status	Description
`Pending`	Transfer created, awaiting policy approval
`Executing`	Approved; being signed and constructed for broadcast
`Broadcasted`	Transaction sent to the network
`Confirmed`	Transaction confirmed on the blockchain
`Failed`	Signing/broadcast failed, or execution reverted on-chain
`Rejected`	Blocked by policy or approval rejected

For what to do when a transfer is stuck in a given status, see Troubleshooting stuck transfers.

Controlling fees and retrying a gas-failed transfer

The transfer endpoint estimates gas for you. The only fee control it exposes is the optional priority field, which accepts Slow, Standard (default), or Fast — under the hood this drives Estimate Fees to pick the fee level. Explicit gas overrides such as gasLimit or maxFeePerGas are not accepted on a transfer request; those exist only on the Sign & Broadcast Transaction endpoint (transaction kind: 'Eip1559'), where you assemble the raw transaction yourself. You set priority when you create a transfer:

const transfer = await dfns.wallets.createTransfer({
  walletId: 'wa-xxx-xxx',
  body: {
    kind: 'Native',
    to: '0x1234...recipient',
    amount: '1000000000000000000',
    priority: 'Fast', // raise the fee level
  },
})

Unsticking a transfer that is already in flight

Never submit a second Transfer Asset request to “retry” a transfer that has not reached a terminal status. If the original later gets mined, you will have sent the funds twice. Only create a new transfer once the previous one is Confirmed, Failed, or Rejected.

To change the fee of — or get rid of — a transfer that is already in progress, act on that transfer instead of creating a new one. On EVM networks:

Speed Up Transfer — for a transfer stuck in Broadcasted (in the mempool but not yet mined). Rebroadcasts the same transfer at a higher fee (the greater of a 10% bump or the Fast level) to get it mined. Use this when you still want the transfer to go through.
Cancel Transfer — for a transfer stuck in Broadcasted that you want to void. Submits a replacement 0-value transaction to your own wallet at the same nonce, nullifying the original. Use this when you no longer want the transfer to land.
Abort Transfer — for a transfer stuck in Executing (approved but not yet broadcast). Marks it Failed without any on-chain action, freeing reserved inputs such as Bitcoin UTXOs.

The safe recovery sequence for a stalled transfer is: cancel or abort it first so it settles to a terminal status, then submit a fresh transfer if you still need to move the funds. Speeding up keeps the original transfer — it does not create a duplicate. See Troubleshooting stuck transfers for the recommended action per status. The raw-transaction flow has the equivalent Speed Up Transaction, Cancel Transaction, and Abort Transaction endpoints.

If you need full control over gas (custom gasLimit, maxFeePerGas, maxPriorityFeePerGas, or replace-by-fee), build the transaction yourself and use Sign & Broadcast Transaction with kind: 'Eip1559' instead of the transfer endpoint.

Listing transfers

List transfers for a wallet:

const transfers = await dfns.wallets.listTransfers({
  walletId: 'wa-xxx-xxx'
})

for (const transfer of transfers.items) {
  console.log(`${transfer.id}: ${transfer.status}`)
}

Handling policy approvals

If a transfer triggers a policy that requires approval, the transfer enters a Pending state:

const transfer = await dfns.wallets.createTransfer({
  walletId: 'wa-xxx-xxx',
  body: {
    kind: 'Native',
    to: '0x1234...recipient',
    amount: '100000000000000000000' // Large amount
  }
})

if (transfer.status === 'Pending') {
  console.log('Transfer requires approval')
  // The transfer will execute automatically once approved
}

See managing policies for working with approvals programmatically.

Monitoring with webhooks

Subscribe to transfer events for real-time updates:

// Subscribe to events
await dfns.webhooks.createWebhook({
  body: {
    url: 'https://your-app.com/webhooks/dfns',
    events: [
      'wallet.transfer.broadcasted',
      'wallet.transfer.confirmed',
      'wallet.transfer.failed'
    ],
    status: 'Enabled'
  }
})

Handle webhook events:

app.post('/webhooks/dfns', async (req, res) => {
  const event = req.body

  switch (event.kind) {
    case 'wallet.transfer.confirmed':
      await handleTransferConfirmed(event.data)
      break
    case 'wallet.transfer.failed':
      await handleTransferFailed(event.data)
      break
  }

  res.status(200).send('OK')
})

See webhooks guide for complete webhook setup.

Polling for status

Alternative to webhooks - poll for transfer status:

async function waitForConfirmation(walletId: string, transferId: string) {
  while (true) {
    const transfer = await dfns.wallets.getTransfer({
      walletId,
      transferId
    })

    if (transfer.status === 'Confirmed') {
      return transfer
    }

    if (transfer.status === 'Failed') {
      throw new Error(`Transfer failed: ${transfer.error}`)
    }

    // Wait before checking again
    await new Promise(resolve => setTimeout(resolve, 5000))
  }
}

See transaction monitoring for polling best practices.

Error handling

Handle common errors:

try {
  const transfer = await dfns.wallets.createTransfer({
    walletId: 'wa-xxx-xxx',
    body: {
      kind: 'Native',
      to: '0x1234...recipient',
      amount: '1000000000000000000'
    }
  })
} catch (error) {
  if (error.status === 403) {
    console.error('Permission denied')
  } else if (error.status === 400) {
    console.error('Invalid request:', error.message)
  } else if (error.message.includes('insufficient balance')) {
    console.error('Insufficient balance for transfer')
  } else {
    console.error('Error creating transfer:', error)
  }
}

Transfer API

Complete API reference

Monitor transactions

Polling patterns

Set up webhooks

Real-time notifications

Manage policies via API

Handle policy approvals

Introduction

Core Concepts

Platform Features

Networks

Solutions

Guides

Advanced

Prerequisites

Creating a native token transfer

Request parameters

Creating an ERC-20 token transfer

Creating an NFT transfer

Transfer with external ID

Checking transfer status

Transfer statuses

Controlling fees and retrying a gas-failed transfer

Unsticking a transfer that is already in flight

Listing transfers

Handling policy approvals

Monitoring with webhooks

Polling for status

Error handling

Transfer API

Monitor transactions

Set up webhooks

Manage policies via API

​Prerequisites

​Creating a native token transfer

​Request parameters

​Creating an ERC-20 token transfer

​Creating an NFT transfer

​Transfer with external ID

​Checking transfer status

​Transfer statuses

​Controlling fees and retrying a gas-failed transfer

​Unsticking a transfer that is already in flight

​Listing transfers

​Handling policy approvals

​Monitoring with webhooks

​Polling for status

​Error handling

​Related documentation

Transfer API

Monitor transactions

Set up webhooks

Manage policies via API

Prerequisites

Creating a native token transfer

Request parameters

Creating an ERC-20 token transfer

Creating an NFT transfer

Transfer with external ID

Checking transfer status

Transfer statuses

Controlling fees and retrying a gas-failed transfer

Unsticking a transfer that is already in flight

Listing transfers

Handling policy approvals

Monitoring with webhooks

Polling for status

Error handling

Related documentation