HIFI Docs

POST

crypto-transfers

curl --request POST \
  --url https://production.hifi.com/v3/crypto-transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestId": "b1e6f0c2-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "currency": "USDC",
  "amount": 100.5,
  "source": {
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV"
  },
  "destination": {
    "walletId": "wlt_9dQ2mNpXwZ7bV1aLcs3Kf"
  },
  "requireApproval": false
}
'

{
  "id": "ctx_3Kf9dQ2mNpXwZ7bV1aLcs",
  "requestId": "b1e6f0c2-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "status": "CREATED",
  "currency": "USDC",
  "amount": "100.5",
  "failedReason": null,
  "source": {
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV"
  },
  "destination": {
    "userId": "usr_7bV1aLcs3Kf9dQ2mNpXwZ",
    "walletId": "wlt_9dQ2mNpXwZ7bV1aLcs3Kf",
    "externalWalletId": null
  },
  "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

Crypto transfer details. Provide exactly one of destination.walletId or destination.externalWalletId. The chain is derived from the source wallet.

Create a single crypto transfer. The chain is derived from the source wallet — it is not supplied in the request. Exactly one of destination.walletId or destination.externalWalletId must be provided.

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

Stablecoin to transfer.

Available options:

USDC,

USDT,

USDG,

PYUSD,

PYUSD0,

USDCX

Example:

"USDC"

amount

number

required

Amount to transfer, greater than zero.

Required range: 0.000001 <= x <= 999999999

Example:

100.5

source

object

required

Show child attributes

destination

object

required

Provide exactly one of walletId or externalWalletId.

Show child attributes

requireApproval

boolean

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

Example:

false

Response

Crypto transfer created successfully.

A single crypto transfer.

string

Public ID of the crypto transfer (prefixed with ctx_).

Example:

"ctx_3Kf9dQ2mNpXwZ7bV1aLcs"

requestId

string<uuid>

Client-supplied idempotency key.

Example:

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

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"

currency

enum<string>

Available options:

USDC,

USDT,

USDG,

PYUSD,

PYUSD0,

USDCX

Example:

"USDC"

amount

string

Transfer amount as a string.

Example:

"100.5"

failedReason

string | null

Reason the transfer failed, when applicable.

Example:

null

source

object

Show child attributes

destination

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 transfer is submitted on-chain.

Show child attributes

chain

enum<string>

Blockchain the 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

curl --request POST \
  --url https://production.hifi.com/v3/crypto-transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "requestId": "b1e6f0c2-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "currency": "USDC",
  "amount": 100.5,
  "source": {
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV"
  },
  "destination": {
    "walletId": "wlt_9dQ2mNpXwZ7bV1aLcs3Kf"
  },
  "requireApproval": false
}
'

{
  "id": "ctx_3Kf9dQ2mNpXwZ7bV1aLcs",
  "requestId": "b1e6f0c2-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "status": "CREATED",
  "currency": "USDC",
  "amount": "100.5",
  "failedReason": null,
  "source": {
    "userId": "usr_3Kf9dQ2mNpXwZ7bV1aLcs",
    "walletId": "wlt_1aLcs3Kf9dQ2mNpXwZ7bV"
  },
  "destination": {
    "userId": "usr_7bV1aLcs3Kf9dQ2mNpXwZ",
    "walletId": "wlt_9dQ2mNpXwZ7bV1aLcs3Kf",
    "externalWalletId": null
  },
  "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 crypto transfer

Authorizations

Body

Response