HIFI Docs

Transfer approvals apply to on-chain stablecoin transfers (Onchain Transfer, including batch transfers), Bridge, and Offramps. Onramps do not support approval workflows.

How Transfer Approvals Work

Create transfer with approval

Include requireApproval: true when creating a transfer via API.

Transfer enters pending state

Transfer status becomes PENDING_APPROVAL and does not execute. A corresponding TransferApproval record is created with status PENDING.

Admin notification

Admins who have opted in to transfer approval emails receive a notification about the pending approval.

Approve or reject

Authorized admins review and either approve or reject the transfer via POST /v3/transfer-approvals/{id}/approve or /reject.

Execution or cancellation

If approved, transfer proceeds (bridge and offramp move to quoting; onchain and batch transfers execute directly). If rejected, the transfer is cancelled.

Implementation Options

Transfer approvals work differently depending on where transactions are initiated:

Dashboard Approvals

When transfers are created in the HIFI Dashboard, whether the transfer requires approval depends only on the initiating profile’s organization role - not on transfer type:

Member-initiated transfers (wallet transfer, batch transfer, bridge, or offramp) always require Admin approval before execution.
Admin-initiated transfers execute without approval, regardless of type.

API Approvals

When using the API:

Include requireApproval: true when creating transfers.
Transfers enter the approval workflow until approved or rejected.
Supported on Onchain Transfer (single and batch), Bridge, and Offramp.
Transactions enter the transfer approval flow only if requireApproval: true is set in the request body - the dashboard role logic above does not apply to API-initiated transfers.
Can be integrated into your application’s approval logic.

Creating Transfers with Approval

Add the requireApproval parameter to any supported transaction endpoint. Request

curl -X POST https://sandbox.hifi.com/v3/crypto-transfers \
  -H "Idempotency-Key: <unique-key>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "requestId": "a40ea2aa-7937-4be9-bb1f-b75f1489bcc6",
    "source": {
      "walletId": "wlt_wOm1XYoNqj4WwJUeL58SI"
    },
    "destination": {
      "walletId": "wlt_8GcOwGmLDQjg24Gq2PXEd"
    },
    "amount": 10000,
    "currency": "USDC",
    "requireApproval": true
  }'

Response

{
    "id": "ctx_HtgURm58uWMF0EzmG8DAl",
    "requestId": "a40ea2aa-7937-4be9-bb1f-b75f1489bcc6",
    "status": "PENDING_APPROVAL",
    "amount": 10000,
    "currency": "USDC"
}

The transfer response itself does not embed the approval object - look up the approval separately via GET /v3/transfer-approvals?status=PENDING or GET /v3/transfer-approvals/{id}.

Supported Endpoints

The requireApproval parameter works with:

Endpoint	Transfer Type
`POST /v3/crypto-transfers`	Single onchain transfers
`POST /v3/batch-transfers`	Batch transfers (up to 50 recipients)
`POST /v3/bridges`	Cross-chain bridging transfers
`POST /v3/offramps`	Offramp transfers (stablecoin to fiat)

Bridging and Offramp Note: for bridging transfers and offramps, quotes are generated after approval. This prevents quotes from expiring while awaiting review.

Listing Pending Approvals

Retrieve all transactions awaiting approval. Cursor-paginated (limit, startingAfter, endingBefore); filter with status. Request

curl "https://sandbox.hifi.com/v3/transfer-approvals?status=PENDING&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
    "data": [
        {
            "id": "ta_QW1e2r3t4y",
            "status": "PENDING",
            "transferId": "ctx_HtgURm58uWMF0EzmG8DAl",
            "transferType": "CRYPTO_TRANSFER",
            "fromDashboard": false,
            "initiatorProfileId": null,
            "createdAt": "2026-07-30T16:11:36.654Z",
            "updatedAt": "2026-07-30T16:11:36.654Z",
            "votes": []
        },
        {
            "id": "ta_Ab12Cd34Ef",
            "status": "PENDING",
            "transferId": "bctx_Gh56Ij78Kl",
            "transferType": "BATCH_CRYPTO_TRANSFER",
            "fromDashboard": true,
            "initiatorProfileId": "prf_8GcOwGmLDQjg24Gq2PXEd",
            "createdAt": "2026-07-30T15:15:00.000Z",
            "updatedAt": "2026-07-30T15:15:00.000Z",
            "votes": []
        }
    ],
    "pagination": {
        "hasMore": false,
        "startCursor": "ta_QW1e2r3t4y",
        "endCursor": "ta_Ab12Cd34Ef"
    }
}

transferType is one of CRYPTO_TRANSFER, BATCH_CRYPTO_TRANSFER, BRIDGE, OFFRAMP. fromDashboard and initiatorProfileId identify dashboard-initiated approvals; both are absent (false / null) for API-initiated ones. Use this endpoint to build approval dashboards or automate approval workflows.

Getting a Transfer Approval

Request

curl "https://sandbox.hifi.com/v3/transfer-approvals/ta_QW1e2r3t4y" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
    "id": "ta_QW1e2r3t4y",
    "status": "PENDING",
    "transferId": "ctx_HtgURm58uWMF0EzmG8DAl",
    "transferType": "CRYPTO_TRANSFER",
    "fromDashboard": false,
    "initiatorProfileId": null,
    "createdAt": "2026-07-30T16:11:36.654Z",
    "updatedAt": "2026-07-30T16:11:36.654Z",
    "votes": []
}

Approving Transfers

Request

curl -X POST https://sandbox.hifi.com/v3/transfer-approvals/ta_QW1e2r3t4y/approve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "comment": "Approved after reviewing transaction details"
  }'

Response

{
    "id": "ta_QW1e2r3t4y",
    "status": "APPROVED",
    "transferId": "ctx_HtgURm58uWMF0EzmG8DAl",
    "transferType": "CRYPTO_TRANSFER",
    "fromDashboard": false,
    "initiatorProfileId": null,
    "createdAt": "2026-07-30T16:11:36.654Z",
    "updatedAt": "2026-07-30T16:14:02.000Z",
    "votes": [
        {
            "approverId": "prf_wOm1XYoNqj4WwJUeL58SI",
            "vote": "APPROVE",
            "comment": "Approved after reviewing transaction details",
            "createdAt": "2026-07-30T16:14:02.000Z"
        }
    ]
}

comment is optional. After approval, onchain and batch transfers execute immediately; bridge and offramp transfers move to quoting (see the quote-timing note above) before executing.

Rejecting Transfers

Request

curl -X POST https://sandbox.hifi.com/v3/transfer-approvals/ta_QW1e2r3t4y/reject \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "comment": "Transfer amount exceeds daily limit"
  }'

Response

{
    "id": "ta_QW1e2r3t4y",
    "status": "REJECTED",
    "transferId": "ctx_HtgURm58uWMF0EzmG8DAl",
    "transferType": "CRYPTO_TRANSFER",
    "fromDashboard": false,
    "initiatorProfileId": null,
    "createdAt": "2026-07-30T16:11:36.654Z",
    "updatedAt": "2026-07-30T16:14:02.000Z",
    "votes": [
        {
            "approverId": "prf_wOm1XYoNqj4WwJUeL58SI",
            "vote": "REJECT",
            "comment": "Transfer amount exceeds daily limit",
            "createdAt": "2026-07-30T16:14:02.000Z"
        }
    ]
}

The reject request body field is comment, the same as approve - not reason. The request body schema rejects unrecognized fields.

Rejected transfers are cancelled and will not execute.

Both approve and reject require the calling profile to have the ADMIN organization role, and the approval must belong to your organization - approvals scoped to other organizations return a 404.

Approval Status

Status	Meaning
`PENDING`	Awaiting admin approval.
`APPROVED`	The underlying transfer proceeds.
`REJECTED`	The underlying transfer is cancelled.
`EXPIRED`	Reserved for a future automatic-expiration mechanism - not currently set by any code path.

Once APPROVED, the underlying transfer moves into its normal status progression (e.g. CREATED → INITIATED → … → COMPLETED).

No automatic expiration today: EXPIRED is a defined status value and appears in the webhook catalog, but nothing in the codebase currently transitions a PENDING approval to EXPIRED - there is no expiration job and no expiration window is enforced. A transfer left in PENDING_APPROVAL stays there indefinitely until an admin approves or rejects it.

Webhooks

Event	Fires when
`TRANSFER_APPROVAL.STATUS.APPROVED`	The approval is approved.
`TRANSFER_APPROVAL.STATUS.REJECTED`	The approval is rejected.

TRANSFER_APPROVAL.CREATED and TRANSFER_APPROVAL.STATUS.PENDING are declared in the webhook event catalog but are never actually emitted - no webhook fires when an approval is created. Poll GET /v3/transfer-approvals?status=PENDING if you need to detect new pending approvals; subscribe to the two events above for the resolution.

Getting Help

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

Onchain Transfer - Single and batch wallet transfers
Bridge - Cross-chain transfers
Offramps - Stablecoin to fiat transfers
Transactions Overview - Transactions resources

Introduction

Core concepts

Features

Compliance

Payments

References

Transfer Approvals

How Transfer Approvals Work

Implementation Options

Dashboard Approvals

API Approvals

Creating Transfers with Approval

Supported Endpoints

Listing Pending Approvals

Getting a Transfer Approval

Approving Transfers

Rejecting Transfers

Approval Status

Webhooks

Getting Help

​How Transfer Approvals Work

​Implementation Options

​Dashboard Approvals

​API Approvals

​Creating Transfers with Approval

​Supported Endpoints

​Listing Pending Approvals

​Getting a Transfer Approval

​Approving Transfers

​Rejecting Transfers

​Approval Status

​Webhooks

​Getting Help

​Related Resources

How Transfer Approvals Work

Implementation Options

Dashboard Approvals

API Approvals

Creating Transfers with Approval

Supported Endpoints

Listing Pending Approvals

Getting a Transfer Approval

Approving Transfers

Rejecting Transfers

Approval Status

Webhooks

Getting Help

Related Resources