Create Institution Transfer

This endpoint initiates a blockchain asset transfer from the institution's vault associated with the auth token. The destination can be an external blockchain address or another institution on the platform.

POST {{host}}/api/v1/transactions/transfer

Request Message Description

#	Field Name	Data Type	Max Length	Required	Description
1	`assetId`	String	-	Yes	Unique identifier of the blockchain asset to transfer
2	`amount`	String	-	Yes	Amount to transfer (decimal string, e.g. `"500.00"`)
3	`clientRef`	String	50	Yes	Unique caller-generated reference (10–50 chars, alphanumeric + hyphens)
4	`note`	String	-	Yes	Narration or description for the transaction
5	`type`	String	-	No	Transfer type (e.g. `VAULT_ACCOUNT_TO_ONE_TIME_ADDRESS`)
6	`address`	String	-	Conditional	Destination blockchain address (required for external transfers)
7	`destinationEntityId`	Integer	-	Conditional	Destination institution ID (required for internal transfers)
8	`transactionId`	String	-	No	Pre-generated transaction ID (optional; system generates if omitted)

Sample Request

{
  "assetId": "CNGN_B75VRLGX_8GWM",
  "amount": "500.00",
  "clientRef": "TXN-20260521-00123",
  "note": "Payment for settlement batch #42",
  "type": "VAULT_ACCOUNT_TO_ONE_TIME_ADDRESS",
  "address": "0xABCD1234.............."
}

Response Message Field Description

#	Field Name	Description
1	`success`	Indicates whether the request was successful
2	`responseCode`	HTTP-like response code (e.g. `200`)
3	`responseMessage`	Human-readable result message
4	`data`	Object containing details of the created transaction
4.1	`data.institutionId`	ID of institution that initiated transfer
4.2	`data.assetId`	Asset transferred
4.3	`data.blockchain`	Blockchain network used
4.4	`data.transactionType`	Transaction type (e.g. TRANSFER)
4.5	`data.amount`	Amount transferred
4.6	`data.feeCharged`	Fee charged for transaction
4.7	`data.status`	Transaction status (e.g. SUBMITTED, COMPLETED)
4.8	`data.subStatus`	Detailed processing status
4.9	`data.transactionId`	System-generated transaction ID
4.10	`data.clientRef`	Caller-provided reference
4.11	`data.transactionHash`	On-chain hash (once available)
4.12	`data.sourceAddress`	Source wallet address
4.13	`data.sourceWalletName`	Source vault name
4.14	`data.destinationAddress`	Destination wallet address
4.15	`data.destinationWalletName`	Destination wallet name (if applicable)
4.16	`data.destinationEntityId`	Destination institution ID (if applicable)
4.17	`data.note`	Transaction narration
4.18	`data.createdAt`	Creation timestamp
4.19	`data.updatedAt`	Last update timestamp

Sample Response (Success)

{
  "success": true,
  "responseCode": "200",
  "responseMessage": "Success",
  "data": {
    "institutionId": 3,
    "assetId": "CNGN_B75VRLGX_8GWM",
    "blockchain": "Base Testnet",
    "transactionType": "TRANSFER",
    "amount": "500.00",
    "feeCharged": "1.50",
    "status": "SUBMITTED",
    "subStatus": "PENDING_AML_SCREENING",
    "transactionId": "ISW-TX-20260521-8F3K",
    "clientRef": "TXN-20260521-00123",
    "transactionHash": null,
    "sourceAddress": "0x632E8..............",
    "sourceWalletName": "Acme Financial Services",
    "destinationAddress": "0xABCD1234..............",
    "destinationWalletName": null,
    "destinationEntityId": null,
    "note": "Payment for settlement batch #42",
    "createdAt": "2026-05-21T10:15:00",
    "updatedAt": "2026-05-21T10:15:01"
  }
}

Sample Response (Failure)

{
  "success": false,
  "responseCode": "400",
  "responseMessage": "Insufficient Balance"
}