This guide will walk through the following steps:

Checking a user's inventory summary - Determination of assets held
Retrieving the lot-level detail for each asset
Combining the lot level detail with asset spot price data to calculate unrealized gain/loss estimates

The guide assumes a tenant scoped {{authToken}} and a {{userId}} have already been obtained using Get a Tenant Scoped Bearer Token and Create TaxBit User APIs.

1. Fetch Inventory Summary

Use the Inventory Summary by Asset API to get a list of all active asset balances and the asset identifiers needed in Step 2.

The code below demonstrates the fetching of the inventory summary with the explicit filter out of any inventory lots with missing cost basis.

curl --request GET \
     --url 'https://api.multi1.enterprise.taxbit.com/v1/inventory/summary?exclude_missing_cost_basis=true' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{authToken}}' \
     --header 'x-user-id: {{userId}}'

The snippet below demonstrates the inventory response showing the balances for two assets: BTC and ETH.

The total_qty.asset.uuid values for each asset will be needed in Step 2.

[
    {
        "total_cost": {
            "asset": {
                "name": "United States Dollar",
                "symbol": "$",
                "code": "USD",
                "type": "Fiat",
                "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396"
            },
            "quantity": "30000.00"
        },
        "updated_datetime": "2023-07-25T17:40:39.281Z",
        "total_qty": {
            "asset": {
                "name": "Bitcoin",
                "symbol": "₿",
                "code": "BTC",
                "type": "Crypto",
                "uuid": "9cd9f4d4-078b-4e44-a308-7662fec0f546"
            },
            "quantity": "2.0"
        }
    },
    {
        "total_cost": {
            "asset": {
                "name": "United States Dollar",
                "symbol": "$",
                "code": "USD",
                "type": "Fiat",
                "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396"
            },
            "quantity": "5250.00"
        },
        "updated_datetime": "2023-07-25T17:40:39.281Z",
        "total_qty": {
            "asset": {
                "name": "Ethereum",
                "symbol": "Ξ",
                "code": "ETH",
                "type": "Crypto",
                "uuid": "b7a005b5-f4d5-44ea-ae80-d4f9e8313558"
            },
            "quantity": "2.5"
        }
    }
]

2. Fetch lot-level detail for each asset

Use the Get Inventory For a Specific Asset API to fetch the inventory details for ETH:

curl --request GET \
     --url 'https://api.multi1.enterprise.taxbit.com/v1/inventory?include_missing_cost_basis=false&asset_id=b7a005b5-f4d5-44ea-ae80-d4f9e8313558' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{authToken}}' \
     --header 'x-user-id: {{userId}}'

An array with all the lots of ETH will be returned. There are two lots in the sample below:

[
    {
        "amount": {
            "asset": {
                "code": "ETH",
                "name": "Ethereum",
                "symbol": "Ξ",
                "type": "Crypto",
                "uuid": "b7a005b5-f4d5-44ea-ae80-d4f9e8313558"
            },
            "quantity": "0.5"
        },
        "acquired_date": "2022-02-01T08:08:08.000Z",
        "term": "Long",
        "unit_cost": {
            "asset": {
                "code": "USD",
                "name": "United States Dollar",
                "symbol": "$",
                "type": "Fiat",
                "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396"
            },
            "quantity": "2500.00"
        },
        "exchange_name": "AcmeExchange",
        "exchange_id": "075a0bec-fbbf-4542-8c31-065497862c23"
    },
    {
        "amount": {
            "asset": {
                "code": "ETH",
                "name": "Ethereum",
                "symbol": "Ξ",
                "type": "Crypto",
                "uuid": "b7a005b5-f4d5-44ea-ae80-d4f9e8313558"
            },
            "quantity": "2.0"
        },
        "acquired_date": "2022-02-01T08:08:08.000Z",
        "term": "Long",
        "unit_cost": {
            "asset": {
                "code": "USD",
                "name": "United States Dollar",
                "symbol": "$",
                "type": "Fiat",
                "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396"
            },
            "quantity": "2000.00"
        },
        "exchange_name": "AcmeExchange",
        "exchange_id": "075a0bec-fbbf-4542-8c31-065497862c23"
    }
]

Repeat the process for BTC using the corresponding assetId from Step 1.

3. Calculate unrealized gain/loss for each lot

Assume the JSON response objects from Step 2 are stored in javascript variables invEth and invBtc. Additionally, assume the current spot price for ETH and BTC are in javascript variables priceEth and priceBtc. The code snippet below will print out the gain/loss amounts for each lot in the user’s inventory.

var invEth = []; // From Step 2
var invBtc = []; // From Step 2
var priceEth = 2000.00; // Curent market price
var priceBtc = 30000.00; // Curent market price

invEth.forEach(lot => console.log("Eth Lot gain: " + lot.amount.quantity * (priceEth - lot.unit_cost.quantity)));

invBtc.forEach(lot => console.log("BTC Log gain: " + lot.amount.quantity * (priceBtc - lot.unit_cost.quantity)));

Note: The guide ignores potential floating point precision issues. Digital asset quantities can use up to 18 decimals of precision, so a BigDecimal type library should be used to parse the JSON responses from the APIs in Step 2.

Conclusion

This guide has demonstrated how to materialize the unrealized gain/loss amount for each lot in the user’s inventory. This data can be exposed on a portfolio performance table or embedded in a trade execution workflow to help users optimize their trading decisions.