Display unrealized gain/loss

Part of Build tax center experiences. Unrealized gain or loss is what a user would gain or lose by selling their holdings at the current price. Taxbit computes it from the account's lots and a price you supply, so the figure lines up with the price the user sees elsewhere in your app.

By the end of this page you can show unrealized gain or loss for an asset and for each of its lots, and you have chosen how to handle holdings without a cost basis.

Before you begin

• A bearer token. See Authenticate your tenant.
• Current inventory for the account. See Real-time inventory.
• The asset's current price from your platform.

Get unrealized gain or loss

Pass the price to GET /v1/inventory as price. The examples continue Set up inventory and gains: the account holds 1.5 ETH that cost $4,875, and ETH is now $3,400.

curl -G $BASE_URL/v1/inventory \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "account_id=acct_5f2e7d10" \
  --data-urlencode "asset_code=ETH" \
  --data-urlencode "price=3400"

{
  "data": {
    "asset": { "code": "ETH", "name": "Ethereum", "type": "Crypto", "uuid": "b7a005b5-f4d5-44ea-ae80-d4f9e8313558" },
    "summary": {
      "total_quantity": "1.5",
      "total_quantity_with_cost_basis": "1.5",
      "total_cost": "4875.00",
      "average_unit_cost": "3250.00",
      "total_current_value": "5100.00",
      "total_unrealized_gain_loss": "225.00",
      "percent_unrealized_gain_loss": "0.04615"
    },
    "lots": [
      {
        "id": "b72696f9-0f10-5827-94c3-289b6366a599",
        "acquisition_datetime": "2026-02-14T16:20:11Z",
        "term": "short-term",
        "quantity": "1.5",
        "fiat_asset_code": "USD",
        "cost": "4875.00",
        "unit_cost": "3250.00",
        "current_value": "5100.00",
        "unrealized_gain_loss": "225.00",
        "percent_unrealized_gain_loss": "0.04615"
      }
    ],
    "lots_ordered_by": "HIFO"
  }
}

• total_current_value and each lot's current_value are the holding's value at your price.
• total_unrealized_gain_loss and each lot's unrealized_gain_loss are what selling at that price would realize.
• percent_unrealized_gain_loss is a ratio, not a percentage: 0.04615 is a 4.6% gain, and -0.5 would be a 50% loss. Multiply by 100 to display it as a percentage.

GET /v1/inventory/summaries does not take a price, so for a portfolio screen, call GET /v1/inventory with a price once per asset, or compute the figures yourself from each summary's total_quantity and total_cost.

Decide how to show holdings without a cost basis

A deposit that arrived without a cost basis adds to what the user holds but has no cost to compare with. total_current_value includes those lots, and total_quantity_missing_cost_basis says how much of the asset they account for; each such lot carries missing_cost_basis: true and no cost. Choose how to present them:

1. Show unrealized gain or loss only for the holdings with a known cost basis, and show the rest separately as missing cost basis. For the asset as a whole, that is (total_quantity - total_quantity_missing_cost_basis) * price - total_cost, and dividing by total_cost gives the ratio. This is the approach we recommend.
2. Treat holdings without a cost basis as costing zero. We don't recommend this: the figure overstates the gain by the full value of those holdings.
3. Treat each deposit's value when it arrived as its cost, so the figure shows what the user gained or lost while holding the asset on your platform. This takes more work to build from the API.

To reduce the gap, let users enter what they paid for transferred assets; see User-provided cost basis.

Where to go next

Tax loss harvesting uses these lot-level figures to find lots that would sell at a loss. Back to Build tax center experiences.