Skip to content

Transfers

Fordefi provides two ways to create asset transfers across all supported chains:

  • Generic transfer API: For the common use-case of transferring assets (native or tokens), Fordefi offers a special-purpose, chain-agnostic Transfer API. This API supports specifying high, low, or medium gas price (in contrast to the chain-specific API).
  • Chain-specific transactions API: For full control over the underlying transaction. For example: customizing gas fields on EVM or providing your own list of instructions on Solana.

Generic transfer API

The Create Transfer endpoint exposes a single, unified format that works consistently across all chains.

Using this API, you can create simple and reliable transfers without needing to use a chain-specific transaction structure.

Once you have specified the chain type, the asset_identifier field provides you a way to specify the asset. Learn more about the different types of supported asset types.

Request signing

Since creating a transaction is a sensitive operation, it requires signing the request. The following examples demonstrate how to create and sign a basic bitcoin transfer in different programming languages. Learn more about request signing.

Example

This sample shows how to programmatically transfer BTC from a Fordefi Bitcoin vault to any arbitrary Bitcoin address on Bitcoin mainnet.

import os
import json
import asyncio
import datetime
from utils.broadcast import broadcast_tx
from utils.sign_payload import sign
from dotenv import load_dotenv

load_dotenv()

async def build_payload(vault_id: str, destination: str, value: str, note: str):
    request_json = {
        "to": {
            "type": "address",
            "address": destination
        },
        "amount": {
            "type": "value",
            "value": value
        },
        "asset_identifier": {
            "type": "utxo",
            "details": {
                "type": "native",
                "chain": "bitcoin_mainnet"
            }
        },
        "note": note,
        "vault_id": vault_id
    }
    
    return request_json

## Fordefi configuration
USER_API_TOKEN = os.environ["FORDEFI_API_TOKEN"]
BTC_VAULT_ID = os.environ["BTC_VAULT_ID"]
path = "/api/v1/transactions/transfer" # https://docs.fordefi.com/api/latest/openapi/transactions/create_transfer_api_v1_transactions_transfer_post
destination = "bc1p...." # CHANGE to your Bitcoin address
value = str(10000) # 0.00001 BTC = 10000 satoshis (1 BTC = 100,000,000 satoshis)
optional_note = "We're all Satoshi!"

async def main():
    try:
        ## Building transaction
        request_json = await build_payload(vault_id=BTC_VAULT_ID, destination=destination, value=value, note=optional_note)
        request_body = json.dumps(request_json)
        timestamp = datetime.datetime.now().strftime("%s")
        payload = f"{path}|{timestamp}|{request_body}"
        ## Signing transaction with API User private key
        signature = await sign(payload=payload)
        ## Push tx to Fordefi for MPC signing and broadcast to network
        await broadcast_tx(path, USER_API_TOKEN, signature, timestamp, request_body)
        print("✅ Transaction submitted successfully!")
    except Exception as e:
        print(f"❌ Transaction failed: {str(e)}")

if __name__ == "__main__":
    asyncio.run(main())

Chain-specific transactions API

This API supports a special-purpose transaction type.

In contrast to the generic transfer API, described above, this API is intended for more advanced scenarios. It allows you to construct chain-specific transactions manually, including transfers, with full flexibility.

To create a transfer transaction, you can set the details.type field within the request body to the transfer type (for example, evm_transfer, solana_transfer, etc.). For more info, see the documentation for the specific chain: EVM, Solana, Bitcoin, Sui, TON, Stacks.

On each of the supported chains, Fordefi supports creating arbitrary tranasctions in their most general form. For example, on EVM chains, you can create an arbitrary contract call, and on Solana, you can execute any list of instructions. That said, for the most common use case of transferring assets (native or tokens), Fordefi supports a special purpose transaction type. To create a transfer transaction, you can set the details.type field within the request body to the transfer type (for example, evm_transfer, solana_transfer, and others). For more info, see the documentation for the specific chain: EVM, Solana, Bitcoin, Sui, TON, Stacks.

Max transfer

To empty your balance of a specific asset, you can set create a maximum-amount transfer transaction, by setting the value.type field to max. Following is an example showing how to construct such a transaction for an ERC-20 token. On all other chains, the valueobject should look the same as in the example below both for native asset and tokens.

{
    "vault_id":"3d3f2a72-6881-4d96-abb1-12341567692c",
    "to":{
      "type":"address",
      "address":"0xC856185610314702c4E8179Bc13e90555F44Ab0E"
     },
     "amount":{
        "type":"max",
        "value":"max"
     },
     "asset_identifier":{
        "type":"evm",
        "details":{
          "type":"native",
          "chain": "ethereum_mainnet",
        }
     },
      "fee_priority":"medium",
      "note":"note"
}
Previous page
Next page