Create Sub-Entity Transfer

This endpoint initiates a blockchain asset transfer from a sub-entity's vault. The transfer is executed on behalf of a specific sub-entity identified by sourceEntityId. Destination can be an external wallet or another platform entity.

POST {{host}}/api/v1/transactions/transfer/sub-entity

Request Message Description

#	Field Name	Data Type	Max Length	Required	Description
1	`sourceEntityId`	String	-	Yes	ID of the sub-entity initiating the transfer
2	`assetId`	String	-	Yes	Unique blockchain asset identifier
3	`amount`	String	-	Yes	Transfer amount (decimal string, e.g. `"200.00"`)
4	`clientRef`	String	50	Yes	Unique transaction reference (10–50 chars, alphanumeric + hyphens)
5	`note`	String	-	Yes	Transaction narration
6	`type`	String	-	No	Transfer type (e.g. `VAULT_ACCOUNT_TO_ONE_TIME_ADDRESS`)
7	`address`	String	-	Conditional	Destination wallet address (required for external transfer)
8	`destinationEntityId`	Integer	-	Conditional	Destination entity ID (required for internal transfers)
9	`transactionId`	String	-	No	Optional pre-generated transaction ID

Sample Request

{
  "sourceEntityId": "78",
  "assetId": "CNGN_B75VRLGX_8GWM",
  "amount": "200.00",
  "clientRef": "TXN-20260521-00456",
  "note": "Sub-entity payout run",
  "type": "VAULT_ACCOUNT_TO_ONE_TIME_ADDRESS",
  "address": "0xDEF05678.............."
}

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.subInstitutionId`	ID of the sub-entity that initiated the transfer
4.3	`data.assetId`	Asset transferred
4.4	`data.blockchain`	Blockchain network used
4.5	`data.transactionType`	Transaction type (e.g. TRANSFER)
4.6	`data.amount`	Amount transferred
4.7	`data.feeCharged`	Fee charged for transaction
4.8	`data.status`	Transaction status (e.g. SUBMITTED, COMPLETED)
4.9	`data.subStatus`	Detailed processing status
4.10	`data.transactionId`	System-generated transaction ID
4.11	`data.clientRef`	Caller-provided reference
4.12	`data.transactionHash`	On-chain hash (once available)
4.13	`data.sourceAddress`	Source wallet address
4.14	`data.sourceWalletName`	Source vault name
4.15	`data.destinationAddress`	Destination wallet address
4.16	`data.destinationWalletName`	Destination wallet name (if applicable)
4.17	`data.destinationEntityId`	Destination institution ID (if applicable)
4.18	`data.note`	Transaction narration
4.19	`data.createdAt`	Creation timestamp
4.20	`data.updatedAt`	Last update timestamp

Sample Response (Success)

{
  "success": true,
  "responseCode": "200",
  "responseMessage": "Success",
  "data": {
    "institutionId": 3,
    "subInstitutionId": 78,
    "assetId": "CNGN_B75VRLGX_8GWM",
    "blockchain": "Base Testnet",
    "transactionType": "TRANSFER",
    "amount": "200.00",
    "feeCharged": "0.80",
    "status": "SUBMITTED",
    "subStatus": "PENDING_AML_SCREENING",
    "transactionId": "ISW-TX-20260521-9G4L",
    "clientRef": "TXN-20260521-00456",
    "transactionHash": null,
    "sourceAddress": "0x94XYZ..............",
    "sourceWalletName": "Acme Sub-entity Alpha",
    "destinationAddress": "0xDEF05678..............",
    "destinationWalletName": null,
    "note": "Sub-entity payout run",
    "createdAt": "2026-05-21T11:00:00",
    "updatedAt": "2026-05-21T11:00:01"
  }
}

Sample Response (Failure)

{
  "success": false,
  "responseCode": "404",
  "responseMessage": "Entity Not Found"
}