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

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.

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

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

​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

Listing transfers

Handling policy approvals

Monitoring with webhooks

Polling for status

Error handling

Related documentation