Crypto Transfers

Create a batch crypto transfer

Create a batch crypto transfer that moves the same stablecoin from one source wallet to up to 50 destinations, each with its own amount. The chain is derived from the source wallet. Each destination must provide exactly one of walletId or externalWalletId.

requestId is an idempotency key: reusing one for an in-flight batch returns a conflict, while reusing one for a settled batch returns the existing transfer. The batch is processed asynchronously after creation.

POST

batch-transfers

curl --request POST \
  --url https://production.hifi.com/v3/batch-transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestId": "d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70",
  "currency": "USDC",
  "source": {
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV"
  },
  "destinations": [
    {
      "walletId": "wlt_9dQ2mNpXwZ7bV1aLcs3Kf",
      "amount": 25
    },
    {
      "externalWalletId": "extw_4mNpXwZ7bV1aLcs3Kf9dQ",
      "amount": 75.5
    }
  ],
  "requireApproval": false
}
'

import requests

url = "https://production.hifi.com/v3/batch-transfers"

payload = {
    "requestId": "d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70",
    "currency": "USDC",
    "source": { "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV" },
    "destinations": [
        {
            "walletId": "wlt_9dQ2mNpXwZ7bV1aLcs3Kf",
            "amount": 25
        },
        {
            "externalWalletId": "extw_4mNpXwZ7bV1aLcs3Kf9dQ",
            "amount": 75.5
        }
    ],
    "requireApproval": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    requestId: 'd3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70',
    currency: 'USDC',
    source: {walletId: 'wlt_1aLcs3Kf9dQ2mNpXwZ7bV'},
    destinations: [
      {walletId: 'wlt_9dQ2mNpXwZ7bV1aLcs3Kf', amount: 25},
      {externalWalletId: 'extw_4mNpXwZ7bV1aLcs3Kf9dQ', amount: 75.5}
    ],
    requireApproval: false
  })
};

fetch('https://production.hifi.com/v3/batch-transfers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://production.hifi.com/v3/batch-transfers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'requestId' => 'd3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70',
    'currency' => 'USDC',
    'source' => [
        'walletId' => 'wlt_1aLcs3Kf9dQ2mNpXwZ7bV'
    ],
    'destinations' => [
        [
                'walletId' => 'wlt_9dQ2mNpXwZ7bV1aLcs3Kf',
                'amount' => 25
        ],
        [
                'externalWalletId' => 'extw_4mNpXwZ7bV1aLcs3Kf9dQ',
                'amount' => 75.5
        ]
    ],
    'requireApproval' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://production.hifi.com/v3/batch-transfers"

	payload := strings.NewReader("{\n  \"requestId\": \"d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70\",\n  \"currency\": \"USDC\",\n  \"source\": {\n    \"walletId\": \"wlt_1aLcs3Kf9dQ2mNpXwZ7bV\"\n  },\n  \"destinations\": [\n    {\n      \"walletId\": \"wlt_9dQ2mNpXwZ7bV1aLcs3Kf\",\n      \"amount\": 25\n    },\n    {\n      \"externalWalletId\": \"extw_4mNpXwZ7bV1aLcs3Kf9dQ\",\n      \"amount\": 75.5\n    }\n  ],\n  \"requireApproval\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://production.hifi.com/v3/batch-transfers")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"requestId\": \"d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70\",\n  \"currency\": \"USDC\",\n  \"source\": {\n    \"walletId\": \"wlt_1aLcs3Kf9dQ2mNpXwZ7bV\"\n  },\n  \"destinations\": [\n    {\n      \"walletId\": \"wlt_9dQ2mNpXwZ7bV1aLcs3Kf\",\n      \"amount\": 25\n    },\n    {\n      \"externalWalletId\": \"extw_4mNpXwZ7bV1aLcs3Kf9dQ\",\n      \"amount\": 75.5\n    }\n  ],\n  \"requireApproval\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://production.hifi.com/v3/batch-transfers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requestId\": \"d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70\",\n  \"currency\": \"USDC\",\n  \"source\": {\n    \"walletId\": \"wlt_1aLcs3Kf9dQ2mNpXwZ7bV\"\n  },\n  \"destinations\": [\n    {\n      \"walletId\": \"wlt_9dQ2mNpXwZ7bV1aLcs3Kf\",\n      \"amount\": 25\n    },\n    {\n      \"externalWalletId\": \"extw_4mNpXwZ7bV1aLcs3Kf9dQ\",\n      \"amount\": 75.5\n    }\n  ],\n  \"requireApproval\": false\n}"

response = http.request(request)
puts response.read_body

{
  "id": "bctx_2mNpXwZ7bV1aLcs3Kf9dQ",
  "requestId": "d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70",
  "currency": "USDC",
  "status": "CREATED",
  "failedReason": null,
  "source": {
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV"
  },
  "destinations": [
    {
      "userId": "usr_7bV1aLcs3Kf9dQ2mNpXwZ",
      "walletId": "wlt_9dQ2mNpXwZ7bV1aLcs3Kf",
      "externalWalletId": null,
      "amount": 25
    },
    {
      "userId": "usr_5Kf9dQ2mNpXwZ7bV1aLcs",
      "walletId": null,
      "externalWalletId": "extw_4mNpXwZ7bV1aLcs3Kf9dQ",
      "amount": 75.5
    }
  ],
  "contractAddress": "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
  "receipt": {
    "transactionHash": null,
    "userOpHash": null
  },
  "chain": "POLYGON",
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Batch crypto transfer details. Between 1 and 50 destinations, each with exactly one of walletId or externalWalletId and its own amount. The chain is derived from the source wallet.

Create a batch crypto transfer that sends the same currency from one source wallet to up to 50 destinations, each with its own amount. The chain is derived from the source wallet. Each destination must supply exactly one of walletId or externalWalletId.

requestId

string<uuid>

required

Client-supplied idempotency key. Reusing a requestId returns the existing transfer or a conflict.

Example:

"b1e6f0c2-1a2b-4c3d-9e8f-0a1b2c3d4e5f"

currency

enum<string>

required

Available options:

USDC,

USDT,

USDG,

PYUSD,

PYUSD0,

USDCX

Example:

"USDC"

source

object

required

Show child attributes

destinations

object[]

required

Between 1 and 50 destinations. Each item provides exactly one of walletId or externalWalletId plus an amount.

Required array length: 1 - 50 elements

Show child attributes

requireApproval

boolean

When true, the batch transfer is created in a pending-approval state and must be approved before execution.

Example:

false

Response

Batch crypto transfer created successfully.

A batch crypto transfer.

string

Public ID of the batch crypto transfer (prefixed with bctx_).

Example:

"bctx_2mNpXwZ7bV1aLcs3Kf9dQ"

requestId

string<uuid>

Client-supplied idempotency key.

Example:

"b1e6f0c2-1a2b-4c3d-9e8f-0a1b2c3d4e5f"

currency

enum<string>

Available options:

USDC,

USDT,

USDG,

PYUSD,

PYUSD0,

USDCX

Example:

"USDC"

status

enum<string>

Available options:

NOT_INITIATED,

CREATED,

PENDING_APPROVAL,

APPROVED,

REJECTED,

EXPIRED,

INITIATED,

PENDING,

COMPLETED,

FAILED,

QUOTE_FAILED,

OPEN_QUOTE,

UNKNOWN,

CANCELLED

Example:

"CREATED"

failedReason

string | null

Reason the batch transfer failed, when applicable.

Example:

null

source

object

Show child attributes

destinations

object[]

Show child attributes

contractAddress

string | null

Token contract address for the transferred currency.

Example:

"0x3c499c542cef5e3811e1192ce70d8cc03d5c3359"

receipt

object

On-chain settlement references. Fields are null until the batch is submitted on-chain.

Show child attributes

chain

enum<string>

Blockchain the batch transfer settles on, derived from the source wallet.

Available options:

ETHEREUM,

POLYGON,

SOLANA,

BASE,

ARBITRUM,

FLOW_EVM,

CANTON,

TRON,

BSC,

ARC

Example:

"POLYGON"

createdAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

updatedAt

string<date-time>

Example:

"2026-07-01T10:30:00.000Z"

⌘I

Create a batch crypto transfer

curl --request POST \
  --url https://production.hifi.com/v3/batch-transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestId": "d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70",
  "currency": "USDC",
  "source": {
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV"
  },
  "destinations": [
    {
      "walletId": "wlt_9dQ2mNpXwZ7bV1aLcs3Kf",
      "amount": 25
    },
    {
      "externalWalletId": "extw_4mNpXwZ7bV1aLcs3Kf9dQ",
      "amount": 75.5
    }
  ],
  "requireApproval": false
}
'

import requests

url = "https://production.hifi.com/v3/batch-transfers"

payload = {
    "requestId": "d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70",
    "currency": "USDC",
    "source": { "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV" },
    "destinations": [
        {
            "walletId": "wlt_9dQ2mNpXwZ7bV1aLcs3Kf",
            "amount": 25
        },
        {
            "externalWalletId": "extw_4mNpXwZ7bV1aLcs3Kf9dQ",
            "amount": 75.5
        }
    ],
    "requireApproval": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    requestId: 'd3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70',
    currency: 'USDC',
    source: {walletId: 'wlt_1aLcs3Kf9dQ2mNpXwZ7bV'},
    destinations: [
      {walletId: 'wlt_9dQ2mNpXwZ7bV1aLcs3Kf', amount: 25},
      {externalWalletId: 'extw_4mNpXwZ7bV1aLcs3Kf9dQ', amount: 75.5}
    ],
    requireApproval: false
  })
};

fetch('https://production.hifi.com/v3/batch-transfers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://production.hifi.com/v3/batch-transfers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'requestId' => 'd3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70',
    'currency' => 'USDC',
    'source' => [
        'walletId' => 'wlt_1aLcs3Kf9dQ2mNpXwZ7bV'
    ],
    'destinations' => [
        [
                'walletId' => 'wlt_9dQ2mNpXwZ7bV1aLcs3Kf',
                'amount' => 25
        ],
        [
                'externalWalletId' => 'extw_4mNpXwZ7bV1aLcs3Kf9dQ',
                'amount' => 75.5
        ]
    ],
    'requireApproval' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://production.hifi.com/v3/batch-transfers"

	payload := strings.NewReader("{\n  \"requestId\": \"d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70\",\n  \"currency\": \"USDC\",\n  \"source\": {\n    \"walletId\": \"wlt_1aLcs3Kf9dQ2mNpXwZ7bV\"\n  },\n  \"destinations\": [\n    {\n      \"walletId\": \"wlt_9dQ2mNpXwZ7bV1aLcs3Kf\",\n      \"amount\": 25\n    },\n    {\n      \"externalWalletId\": \"extw_4mNpXwZ7bV1aLcs3Kf9dQ\",\n      \"amount\": 75.5\n    }\n  ],\n  \"requireApproval\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://production.hifi.com/v3/batch-transfers")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"requestId\": \"d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70\",\n  \"currency\": \"USDC\",\n  \"source\": {\n    \"walletId\": \"wlt_1aLcs3Kf9dQ2mNpXwZ7bV\"\n  },\n  \"destinations\": [\n    {\n      \"walletId\": \"wlt_9dQ2mNpXwZ7bV1aLcs3Kf\",\n      \"amount\": 25\n    },\n    {\n      \"externalWalletId\": \"extw_4mNpXwZ7bV1aLcs3Kf9dQ\",\n      \"amount\": 75.5\n    }\n  ],\n  \"requireApproval\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://production.hifi.com/v3/batch-transfers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"requestId\": \"d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70\",\n  \"currency\": \"USDC\",\n  \"source\": {\n    \"walletId\": \"wlt_1aLcs3Kf9dQ2mNpXwZ7bV\"\n  },\n  \"destinations\": [\n    {\n      \"walletId\": \"wlt_9dQ2mNpXwZ7bV1aLcs3Kf\",\n      \"amount\": 25\n    },\n    {\n      \"externalWalletId\": \"extw_4mNpXwZ7bV1aLcs3Kf9dQ\",\n      \"amount\": 75.5\n    }\n  ],\n  \"requireApproval\": false\n}"

response = http.request(request)
puts response.read_body

{
  "id": "bctx_2mNpXwZ7bV1aLcs3Kf9dQ",
  "requestId": "d3a8b2e4-3c4d-4e5f-9012-2b3c4d5e6f70",
  "currency": "USDC",
  "status": "CREATED",
  "failedReason": null,
  "source": {
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV"
  },
  "destinations": [
    {
      "userId": "usr_7bV1aLcs3Kf9dQ2mNpXwZ",
      "walletId": "wlt_9dQ2mNpXwZ7bV1aLcs3Kf",
      "externalWalletId": null,
      "amount": 25
    },
    {
      "userId": "usr_5Kf9dQ2mNpXwZ7bV1aLcs",
      "walletId": null,
      "externalWalletId": "extw_4mNpXwZ7bV1aLcs3Kf9dQ",
      "amount": 75.5
    }
  ],
  "contractAddress": "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
  "receipt": {
    "transactionHash": null,
    "userOpHash": null
  },
  "chain": "POLYGON",
  "createdAt": "2026-07-01T10:30:00.000Z",
  "updatedAt": "2026-07-01T10:30:00.000Z"
}

{
  "type": "VALIDATION_ERROR",
  "message": "One or more fields are invalid or missing.",
  "fields": [
    {
      "code": "invalid_value",
      "message": "Must be a valid email address",
      "field": "email"
    }
  ]
}

{
  "type": "UNAUTHORIZED",
  "message": "Authentication required"
}

{
  "type": "RESOURCE_CONFLICT",
  "message": "Resource already exists or conflicts with current state"
}

{
  "type": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred"
}

Overview

Endpoints

Create a batch crypto transfer

Authorizations

Body

Response