Net Asset Value (NAV) is the total value of an asset minus its liabilities, divided by the number of shares (tokens), representing the per-token value of the asset. This data is defined and managed by the issuers.

The NAV is an important data point for your token. Setting the NAV can have implications on pending primary market orders, secondary market valuation, investor appreciation of your asset etc. For this reason, we highly recommend exercising extreme caution before submitting any new NAV.

When added, the value will appear on the Investor Portal, showing the total value owned by each investor.

📘

Prerequisites:

To complete this use case, you will need to authenticate your request(s). You can generate your token by following these steps:

• Make sure to leverage an exisintg account, e.g. Agent, Owner...
• Sign into your Servicing portal to disable your 2FA.
• Navigate to the "Getting API access" page to generate the required JWT, thanks to your credentials.
• Add the JWT to the header of your request.

To manage the NAV, please make sure to connect to the API with an Agent JWT.

1. Getting the token_id

The NAV is managed per token (asset). Each of your tokens has its own NAV. Therefore, for the API to know what token you are updating the NAV for, you will need to pass a token identifier to the API.

In other words, to manage the NAV by API, you will need to leverage a {{token_id}}, which is an identifier such as “3a369172-cd22-4e54-8f39-d852d716143d”. Each token has a unique {{token_id}}. Before sending the NAV, you first need to retrieve the {{token_id}}.

To do so, call the following endpoint for the purpose of retrieving the {{token_id}}. Your account should be either an Owner and/or an Agent.

cURL request

curl -XGET 'https://api-testing.tokeny.com/servicing/api/tokens' \
  -H 'authorization: Bearer <jwt>'

Response

[  
    {  
        "id": "3a360372-cd32-4e64-8FG39-d323d716143O",  
        "address": "string",  
        "decimals": 0,  
        "image": "https\://…",  
        "isPaused": true,  
        "tradable": true,  
        "name": "string",  
        "symbol": "string",  
        "type": "string",  
        "protocol": "T-REX",  
        "blockchainNetwork": "string",  
        "identityRegistryStorage": "0x…",  
        "permissions": [  
            "string"  
        ],  
        "agentWallet": "0x…"  
    }  
]

This answer will list all your tokens for this account, with basic data for each of them, including the “id” field. This “id” is the {{token_id}} you will leverage in the next sections.

2. Getting the NAVs

Once you have the token_id, you can start interacting with the NAV.

First, you might want to get the current and past NAVs. To do so, call the following endpoint:

cURL request

curl -XGET 'https://https://https://api-testing.tokeny.com/servicing/api/tokens/:token_id/valuation' \
  -H 'authorization: Bearer <jwt>'

As you can see, there is a variable called {{token_id}}, this is where you need to replace this variable with the token_id of the token you would like to get the NAVs for.

Response

{  
    "history": [  
        {  
            "date": "2025-01-01T13:00:00",  
            "valuation": "1100",  
            "currency": "USD"  
        },  
        {  
            "date": "2000-01-01T11:00:00",  
            "valuation": "1000",  
            "currency": "USD"  
        }]  
}

As a result, you will get an answer from Tokeny’s API with the list of all the previous NAVs for this token. If no NAV has been previously set, you will receive an empty array.

3. Updating the NAV

⚠️

IMPORTANT: valuation should not be sent with more than two decimals. This would break the usability of your token.

📘

The representation of the date and time for the NAV should be sent in the ISO 8601 format.

To add a NAV or modify the NAV of a token, let's use the following endpoint:

cURL request

curl -XPOST 'https://api-testing.tokeny.com/servicing/api/tokens/:token_id/valuation' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json' \
  --data-binary '{
    "valuation": "1000",
    "date": "2022-12-07 11:00:00.000",
    "currency": "USD"
}'

Response

{  
        "id": "3a360372-cd32-4e64-8FG39-d323d716143O",  
        "address": "string",  
        "decimals": 0,  
        "image": "https\://…",  
        "isPaused": true,  
        "tradable": true,  
        "name": "string",  
        "symbol": "string",  
        "type": "string",  
        "protocol": "T-REX",  
        "blockchainNetwork": "string",  
        "identityRegistryStorage": "0x…",  
        "permissions": [  
            "string"  
        ],  
        "agentWallet": "0x…"  
    },
    "trustedIssuers": [
        {
            "address": "string",
            "trustedTopics": [
                string
            ]
        }
    ],
    "issuer": {
        "id": "string",
        "name": "string"
    },
    "website": null,
    "linkedIn": null,
    "medium": null,
    "instagram": null,
    "facebook": null,
    "telegram": null,
    "faq": null,
    "twitter": null,
    "youtube": null,
    "currency": "string"
}