Forced transfer

A forced transfer moves assets from one holder address to another without the holder initiating or signing the movement. Use it only for governed exception cases, such as legal orders, approved recovery procedures, or compliance events that require a custodian to move assets. The API submits one contract call for a single item, a batch contract call for small lists, and durable queued execution for larger reviewed lists.

The diagram shows the execution boundary. DALP validates the custodian caller and wallet verification before it chooses the contract path. One item uses forcedTransfer. A small reviewed list uses batchForcedTransfer. A larger list is accepted as queued work and can produce more than one transaction hash as chunks finish.

A forced transfer is an exception path that moves token supply through custodian authority rather than holder initiation.

For the web interface workflow, see Forced transfer. For the broader holder-transfer API reference, see Token holders and transfers.

Prerequisites

• API key for a user with the asset's Custodian role
• Wallet verification method for the signing account, when required by the platform
• Token contract address for the asset you want to administer
• Source holder address, recipient address, and amount in the asset's base units
• Approval evidence for the exception workflow

Execute one forced transfer

Send the token address in the path and the forced-transfer item in the transfers array:

curl -X POST https://your-platform.example.com/api/v2/tokens/0xTOKEN/forced-transfers \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "transfers": [
      {
        "from": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
        "recipient": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
        "amount": "1000000000000000000"
      }
    ]
  }'

The API validates the caller's role, wallet verification, request shape, and token state before it submits or queues the transaction. A synchronous response returns the token resource with meta.txHashes. An asynchronous response returns a transactionId, status, and statusUrl for polling.

{
  "transactionId": "018f2f2b-7c8a-7b40-9d46-5b5a51b8e3a1",
  "status": "accepted",
  "statusUrl": "/api/v2/transaction-requests/018f2f2b-7c8a-7b40-9d46-5b5a51b8e3a1"
}

Store the transaction identifier or hash with the approval evidence for the exception.

Understand batch execution

The transfers array decides how DALP submits the operation:

The request schema accepts at least one item and at most 10,000 items. Use an idempotency key when retrying the same API submission so a network retry does not create a duplicate queued operation. Large batches can surface more than one transaction hash under that queued operation.

Use this decision rule before submitting a reviewed list:

1. Send one item when the exception affects one holder balance.
2. Send 2 to 10 items when the reviewed exception list is small enough to treat as one operational batch.
3. Send more than 10 items only when the approval record already covers the full list and your reconciliation process can track multiple transaction hashes under one queued operation.

Execute batch forced transfers

The same endpoint accepts multiple forced-transfer items. Each item carries its own source address, recipient address, and amount:

curl -X POST https://your-platform.example.com/api/v2/tokens/0xTOKEN/forced-transfers \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "transfers": [
      {
        "from": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
        "recipient": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
        "amount": "1000000000000000000"
      },
      {
        "from": "0x1234567890AbCdEf1234567890AbCdEf12345678",
        "recipient": "0xabcdef1234567890abcdef1234567890abcdef12",
        "amount": "500000000000000000"
      }
    ]
  }'

Batch forced-transfer requests can include up to 10,000 items. For operational control, keep each API request aligned with one reviewed approval record. If your approval process creates separate case files, submit separate requests so each result maps cleanly to the case that authorized it.

Request body

What to verify after submission

After the request queues or completes, verify the operation with the same evidence standards you use for other asset-servicing exceptions:

1. Confirm the affected holder balances or transfer events through your operating view or API integration.
2. Record the token address, source address, recipient address, amount, approving operator, request identifier, and transaction hashes.
3. Keep the legal or compliance approval evidence outside the API request.
4. For queued batches, reconcile every completed chunk before closing the operating record.

Troubleshooting

Related guides

• Forced transfer for the web interface workflow
• Token holders and transfers for transfer, freeze, unfreeze, and recovery endpoints
• Token events for event-based reconciliation after the write
• Track asynchronous transactions for polling queued transaction status
• Per-asset RBAC for Custodian role context