HIFI Docs

Transfer Types

HIFI supports two types of wallet transfers:

Type	Description	Best For
Single Transfer	Send to one recipient	Individual payments, one-time transactions
Batch Transfer	Send to up to 50 recipients in a single transaction	Payroll, airdrops, bulk distributions

Creating Single Transfers

Send stablecoins to a single recipient on the same blockchain.

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/transfers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "userId": "usr_abc123"
    },
    "destination": {
      "userId": "usr_xyz789"
    },
    "amount": 10,
    "currency": "usdc",
    "chain": "POLYGON",
    "requestId": "a40ea2aa-7937-4be9-bb1f-b75f1489bcc6"
  }'

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/transfers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "userId": "usr_abc123"
    },
    "destination": {
      "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    },
    "amount": 10,
    "currency": "usdc",
    "chain": "POLYGON",
    "requestId": "b51fb3bb-8a48-5cfa-cc2g-c86g2589cdd7"
  }'

The response contains the transfer details:

Response

{
  "transferType": "WALLET.TRANSFER",
  "transferDetails": {
    "id": "xfr_abc123",
    "requestId": "a40ea2aa-7937-4be9-bb1f-b75f1489bcc6",
    "createdAt": "2025-09-26T03:04:11.092Z",
    "updatedAt": "2025-09-26T03:04:11.092Z",
    "chain": "POLYGON",
    "currency": "usdc",
    "contractAddress": "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
    "status": "CREATED",
    "failedReason": null,
    "source": {
      "userId": "usr_abc123",
      "walletAddress": "0x1b932E54e77Aeb698144550d5a493Ea99E20Daa7",
      "walletType": "INDIVIDUAL"
    },
    "destination": {
      "userId": "usr_xyz789",
      "walletAddress": "0x1b932E54e77Aeb688144550d5a493Ea99E20Daa7"
    },
    "amount": 10,
    "receipt": {
      "transactionHash": null,
      "userOpHash": null
    }
  }
}

string

Unique transfer ID. Use this to check status using the Retrieve a crypto transfer endpoint.

string

Transfer status. Progression: CREATED → INITIATED → PENDING → COMPLETED. See Transaction Status for details.

object

Details about the sender including wallet address and user information.

object

Details about the recipient including wallet address and user information (if HIFI user).

number

Transfer amount in the specified currency.

object

Blockchain transaction receipt. Contains transactionHash and userOpHash once the transfer is confirmed on-chain.

For detailed response field documentation, see the Create Crypto Transfer API reference.

Creating Batch Transfers

Send stablecoins to up to 50 recipients on the same blockchain.

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/transfers/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "userId": "usr_abc123"
    },
    "destinations": [
      {
        "userId": "usr_xyz789",
        "amount": 10
      },
      {
        "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "amount": 5
      }
    ],
    "currency": "usdc",
    "chain": "POLYGON",
    "requestId": "c62gc4cc-9b59-6dgb-dd3h-d97h3690dee8"
  }'

External Wallet Registration: External wallet addresses in batch transfers must be registered before use. Register them using the External Wallets API.

Let’s take a look at the response:

Response

{
  "transferType": "WALLET.TRANSFER.BATCH",
  "transferDetails": {
    "id": "bat_abc123",
    "requestId": "c62gc4cc-9b59-6dgb-dd3h-d97h3690dee8",
    "createdAt": "2025-04-05T00:55:50.609Z",
    "updatedAt": "2025-04-05T00:56:33.236Z",
    "chain": "POLYGON",
    "currency": "usdc",
    "contractAddress": "0x41e94eb019c0762f9bfcf9fb1e58725bfb0e7582",
    "status": "COMPLETED",
    "source": {
      "userId": "usr_abc123",
      "walletAddress": "0x99a8c5ED386d217BC6ff0AA1b3585606D475432B",
      "walletType": "INDIVIDUAL"
    },
    "destination": {
      "batch": [
        {
          "amount": "10",
          "userId": "usr_xyz789",
          "walletAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
        },
        {
          "amount": "5",
          "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
        }
      ]
    },
    "receipt": {
      "transactionHash": "0x57f0cd3429ea425d982882243428ef4a1eda5f1be2157c1b34ea48b49b24fe7f",
      "userOpHash": "0xef7bdb071b1fcfb5df629bd4d27ffa6dc32d0a5df676f26fb8c25311df1185ac"
    }
  }
}

string

Unique batch transfer ID. Use this to check status using the Retrieve a crypto transfer endpoint.

string

Batch transfer status. Progression: CREATED → INITIATED → PENDING → COMPLETED. See Transaction Status for details.

object

Details about the sender including wallet address and user information.

array

Array of destination recipients. Each item contains amount, optional userId (for HIFI users), and walletAddress.

object

Blockchain transaction receipt. Contains transactionHash and userOpHash once the transfer is confirmed on-chain.

For detailed field documentation, see the Create Batch Transfer API reference.

Transfer Status

Wallet transfets progress through several statuses:

Status	Description
NOT_INITIATED	Transfer not submitted due to validation error
CREATED	Transfer request created and awaiting processing
INITIATED	Transfer submitted to blockchain
PENDING	Transaction awaiting on-chain confirmation
COMPLETED	Transfer successfully confirmed on-chain
FAILED	Transfer failed (check `failedReason` for details)
UNKNOWN	Transfer status could not be determined

Tracking Transfers

Status Updates: Subscribe to WALLET.TRANSFER.UPDATE webhook events to receive real-time status notifications. See Webhooks for setup instructions.

Monitor transaction status using the Retrieve Crypto Transfer endpoint. The response structure matches the create endpoint shown above.

curl -X GET "https://sandbox.hifibridge.com/v2/wallets/transfers/xfr_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use the transactionHash in the response to view the transaction on a blockchain explorer like Polygonscan or Etherscan.

Transaction Approvals

For organizations requiring multi-party authorization, all transactions support an optional approval workflow.

How Approvals Work

Enable approval requirement

Set requireApproval: true when creating a transaction.

Review pending transaction

The transaction enters PENDING_APPROVAL status. Dashboard admins are notified via email and webhook to approve or reject the transaction. Any admin can make the decision.

Execution or rejection

If approved, the transaction is executed. If rejected, it’s cancelled.

Request with approval:

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/transfers/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "userId": "usr_abc123"
    },
    "destinations": [...],
    "currency": "usdc",
    "chain": "POLYGON",
    "requireApproval": true,
    "requestId": "c62gc4cc-9b59-6dgb-dd3h-d97h3690dee8"
  }'

When approval is required, the response includes approval details:

Response

{
  "transferDetails": {
    "id": "bat_abc123",
    "status": "PENDING_APPROVAL",
    "receipt": {
      "approval": {
        "id": "apv_xyz789",
        "status": "PENDING",
        "transferId": "bat_abc123",
        "transferType": "WALLET.TRANSFER.BATCH",
        "votes": [
          {
            "approverId": "profile_abc123",
            "vote": "APPROVE",
            "comment": "Approved for processing",
            "createdAt": "2025-02-03T16:12:41.503+00:00"
          }
        ]
      }
    }
  }
}

string

Transfer status. When requireApproval: true is set, the status will be PENDING_APPROVAL until approved.

object

Approval object containing approval details and votes when approval is required.

Show properties

string

Unique approval ID.

string

Approval status: PENDING, APPROVED, or REJECTED.

array

Array of approval votes. Each vote contains approverId, vote (APPROVE/REJECT), optional comment, and createdAt.

Configuring Approvers: Manage your team roles in the HIFI Dashboard. Members can create transactions, but only admins can approve.

Key Concepts

HIFI vs External Transactions

HIFI transactions use userId as the destination while external transactions use a walletAddress as the destination.

Registration Required: External wallet addresses must be registered before use. Create an external wallet record using the External Wallets API before including the address in transaction requests.

Batch Transaction Limits

Batch transactions have the following constraints: - Maximum recipients: 50 per batch - Supported chains: Currently POLYGON only - Supported currencies: USDC, USDT If you need to send to more than 50 recipients, create multiple batches.

Transaction Receipts

The receipt object provides blockchain verification:

transactionHash: Unique identifier for the blockchain transaction. Use this to view the transaction on block explorers.
userOpHash: For account abstraction wallets, this is the user operation hash

Both values are null until the transaction is confirmed on-chain (status becomes COMPLETED).

Getting Help

📧 Email: support@hifi.com
💬 Slack: Message us in our shared Slack channel

Wallets - Understand wallet addresses and balances
Webhooks - Real-time transaction status notifications
API: Single Transfer - Complete single transfer documentation
API: Batch Transfer - Complete batch transfer documentation

Introduction

Core concepts

Features

Compliance

Payments

References

Transfers

Transfer Types

Creating Single Transfers

Creating Batch Transfers

Transfer Status

Tracking Transfers

Transaction Approvals

How Approvals Work

Key Concepts

Getting Help

​Transfer Types

​Creating Single Transfers

​Creating Batch Transfers

​Transfer Status

​Tracking Transfers

​Transaction Approvals

​How Approvals Work

​Key Concepts

​Getting Help

​Related Resources

Transfer Types

Creating Single Transfers

Creating Batch Transfers

Transfer Status

Tracking Transfers

Transaction Approvals

How Approvals Work

Key Concepts

Getting Help

Related Resources