Fetch Institution Profile

This endpoint retrieves the full profile of the institution associated with the auth token, including its balance information across all registered blockchain assets.

GET {{host}}/api/v1/institutions/profile

Response Message Field Description

#	Field Name	Description
1	`success`	Indicates whether the request was successful (`true` for success)
2	`responseCode`	HTTP-like response code (e.g. `200` for success)
3	`responseMessage`	Human-readable result message (e.g. `Success`)
4	`data`	Object containing the institution's full profile and balance details
4.1	`data.id`	Unique internal identifier of the institution
4.2	`data.institutionName`	Display name of the institution
4.3	`data.institutionCode`	Alphanumeric code identifying the institution
4.4	`data.email`	Contact email address of the institution
4.5	`data.category`	Institution category (e.g. IMTO, WAAS)
4.6	`data.countryCode`	ISO 3166-1 alpha-2 country code of the institution
4.7	`data.currencyCode`	ISO 4217 currency code of the institution's base currency
4.8	`data.vaultId`	Vault identifier assigned to the institution
4.9	`data.kycTier`	KYC tier level of the institution
4.10	`data.kycStatus`	Current KYC verification status
4.11	`data.enabled`	Whether the institution is currently active
4.12	`data.onRampEnabled`	Whether on-ramp transactions are enabled
4.13	`data.offRampEnabled`	Whether off-ramp transactions are enabled
4.14	`data.webhookUrl`	Webhook URL configured for event notifications
4.15	`data.balanceInformation`	Object containing asset balance and metadata details
4.15.1	`data.balanceInformation.balances`	Array of balance objects, one per registered asset
4.15.1.1	`data.balanceInformation.balances[].institutionId`	Unique internal ID of the institution
4.15.1.2	`data.balanceInformation.balances[].vaultId`	Vault identifier for this asset
4.15.1.3	`data.balanceInformation.balances[].assetId`	Unique identifier of the blockchain asset
4.15.1.4	`data.balanceInformation.balances[].address`	Blockchain wallet address for this asset
4.15.1.5	`data.balanceInformation.balances[].availableBalance`	Current available balance for the asset
4.15.1.6	`data.balanceInformation.balances[].frozenBalance`	Amount of the asset currently frozen
4.15.2	`data.balanceInformation.assetInfo`	Array of asset metadata objects corresponding to balances
4.15.2.1	`data.balanceInformation.assetInfo[].id`	Unique identifier of the asset
4.15.2.2	`data.balanceInformation.assetInfo[].displayName`	Human-readable name of the asset
4.15.2.3	`data.balanceInformation.assetInfo[].displaySymbols`	Display ticker symbol of the asset
4.15.2.4	`data.balanceInformation.assetInfo[].onChainDecimals`	Number of decimal places used on-chain
4.15.2.5	`data.balanceInformation.assetInfo[].blockchainId`	Blockchain network identifier
4.15.2.6	`data.balanceInformation.assetInfo[].blockchainDisplayName`	Display name of the blockchain network

Sample Response (Success)

{
  "success": true,
  "responseCode": "200",
  "responseMessage": "Success",
  "data": {
    "id": 3,
    "institutionName": "Acme Financial Services",
    "institutionCode": "ACME001",
    "email": "[email protected]",
    "category": "WAAS",
    "countryCode": "NG",
    "currencyCode": "NGN",
    "vaultId": "45",
    "kycTier": "TIER_3",
    "kycStatus": "APPROVED",
    "enabled": true,
    "onRampEnabled": true,
    "offRampEnabled": false,
    "webhookUrl": "https://acmefinancial.com/webhooks",
    "balanceInformation": {
      "balances": [
        {
          "institutionId": 3,
          "vaultId": "45",
          "assetId": "CNGN_B75VRLGX_8GWM",
          "address": "0x632E8..............",
          "availableBalance": "5000.00",
          "frozenBalance": "0"
        }
      ],
      "assetInfo": [
        {
          "id": "CNGN_B75VRLGX_8GWM",
          "displayName": "Cardano Nigerian Naira",
          "displaySymbols": "cNGN",
          "onChainDecimals": 6,
          "blockchainId": "BASE_TEST",
          "blockchainDisplayName": "Base Testnet"
        }
      ]
    }
  }
}

Sample Response (Failure)

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