Consuming Gains

So far we’ve only accumulated inventory with trade transactions that received crypto assets (BTC and ETH) in exchange for fiat assets (USD). Below we POST a transaction that sells 1.5 bitcoin for $90,000; subsequent requests to /inventory* and /gains* endpoints reflect the disposal:

POST the sell transaction:

curl --request POST \
  --url https://api.multi1.enterprise.taxbit.com/v1/transactions/external-id \
  --header 'authorization: Bearer {{token}}' \
  --header 'content-type: application/json' \
  --data '{
    "account_id": "{{account-id}}",
    "id": "4",
    "datetime": "2024-01-04T12:13:14.123Z",
    "type": "trade",
    "received": [
        {
            "asset_amount": {
                "amount": "90000.00",
                "asset": {
                    "code": "USD",
                    "type": "fiat"
                }
            },
            "rates": [
                {
                    "amount": "1.00",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    }
                }
            ]
        }
    ],
    "sent": [
        {
            "asset_amount": {
                "amount": "1.5",
                "asset": {
                    "code": "BTC",
                    "type": "crypto"
                }
            },
            "rates": [
                {
                    "amount": "60000.00",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    }
                }
            ]
        }
    ],
    "version": "2.0"
}
'

Bitcoin inventory now shows 0.5 BTC remaining with an average unit cost of $20,005. The sale fully disposed of the higher-cost ($40,005) lot and partially disposed of the lower-cost ($20,005) lot because the account’s payer is configured to use the HIFO (highest-in-first-out) disposition method. Accounts can also use a FIFO (first-in-first-out) method, which selects lots based on the earliest acquisition_datetime.

curl --request GET \
  --url 'https://api.multi1.enterprise.taxbit.com/v1/inventory?account_id={{account-id}}&asset_code=BTC' \
  --header 'authorization: Bearer {{token}}'
HTTP/1.1 200 OK
Content-Type: application/json

{

  "data": {

    "asset": {

      "uuid": "9cd9f4d4-078b-4e44-a308-7662fec0f546",
      "name": "Bitcoin",
      "code": "BTC",
      "type": "Crypto"
    },
    "fiat_asset": {

      "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
      "name": "United States Dollar",
      "code": "USD",
      "type": "Fiat"
    },
    "summary": {

      "total_quantity": "0.5",
      "total_cost": "10002.5",
      "average_unit_cost": "20005",
      "total_quantity_with_cost_basis": "0.5"
    },
    "lots": [
      {

        "id": "c8627a07-3492-5e91-827d-94d4094240b0",
        "acquisition_datetime": "2024-01-01T12:13:14.123Z",
        "term": "short-term",
        "quantity": "0.5",
        "fiat_asset_code": "USD",
        "cost": "10002.5",
        "unit_cost": "20005"
      }
    ]
  }
}

Disposal data can be queried via TaxBit’s /gains* endpoints, which each require start_date and end_date query parameters.

/v1/gains/breakdown

The /v1/gains/breakdown endpoint returns quantity for both short- and long-term gains. Long-term gains are defined as disposed inventory held for at least a year prior to disposal.

curl --request GET \
  --url 'https://api.multi1.enterprise.taxbit.com/v1/gains/breakdown?start_date=2020-01-01T00%3A00%3A00Z&end_date=2025-01-01T00%3A00%3A00Z&account_id={{account-id}}' \
  --header 'authorization: Bearer {{token}}'

HTTP/1.1 200 OK
Content-Type: application/json

{

  "long_term": {

    "asset": {

      "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
      "name": "United States Dollar",
      "type": "Fiat",
      "code": "USD"
    },
    "quantity": "0"
  },
  "short_term": {

    "asset": {

      "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
      "name": "United States Dollar",
      "type": "Fiat",
      "code": "USD"
    },
    "quantity": "39992.5"
  },
  "total": {

    "asset": {

      "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
      "name": "United States Dollar",
      "type": "Fiat",
      "code": "USD"
    },
    "quantity": "39992.5"
  }
}

/v1/gains/summary

The /v1/gains/summary endpoint returns the total gain quantity (short- and long-term) for the given request’s time period.

	curl --request GET \
  --url 'https://api.multi1.enterprise.taxbit.com/v1/gains/summary?start_date=2020-01-01T00%3A00%3A00Z&end_date=2025-01-01T00%3A00%3A00Z&account_id={{account-id}}' \
  --header 'authorization: Bearer {{token}}'


HTTP/1.1 200 OK
Content-Type: application/json

{
  "quantity": "39992.5",
  "asset": {
    "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
    "name": "United States Dollar",
    "type": "Fiat",
    "code": "USD"
  }
}

/v1/gains/cost-bases

The /v1/gains/cost-bases endpoint returns data for specific taxable disposals that took place during the request’s time period.

curl --request GET \
  --url 'https://api.multi1.enterprise.taxbit.com/v1/gains/cost-bases?start_date=2020-01-01T00%3A00%3A00Z&end_date=2025-01-01T00%3A00%3A00Z&account_id={{account-id}}' \
  --header 'authorization: Bearer {{token}}'

HTTP/1.1 200 OK
Content-Type: application/json

[

  {

    "sale_date": "2024-01-04T12:13:14.123Z",
    "amount_sold": {

      "asset": {

        "uuid": "9cd9f4d4-078b-4e44-a308-7662fec0f546",
        "name": "Bitcoin",
        "type": "Crypto",
        "code": "BTC"
      },
      "quantity": "1"
    },
    "proceeds": {

      "asset": {

        "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
        "name": "United States Dollar",
        "type": "Fiat",
        "code": "USD"
      },
      "quantity": "60000"
    },
    "gain_type": "short-term",
    "tax_year": "2024",
    "user_id": "6a33f4fa-f9cf-445e-ae59-496c4bde213a",
    "index": "lot-id=bb694f5c-d2ef-5ff9-82cc-a73ace56db0c,fee=false",
    "acquisition_transaction_id": "78665eb7-43de-5649-ad93-ca62fc1c1295",
    "disposition_transaction_id": "15955016-a10b-5fcd-9e65-3af6d0cf6a09",
    "update_time": "2024-07-02T19:23:13.402419Z",
    "gain": {

      "asset": {

        "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
        "name": "United States Dollar",
        "type": "Fiat",
        "code": "USD"
      },
      "quantity": "19995"
    },
    "cost": {

      "asset": {

        "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
        "name": "United States Dollar",
        "type": "Fiat",
        "code": "USD"
      },
      "quantity": "40005"
    },
    "cost_basis_date": "2024-01-02T12:13:14.123Z"
  },
  {

    "sale_date": "2024-01-04T12:13:14.123Z",
    "amount_sold": {

      "asset": {

        "uuid": "9cd9f4d4-078b-4e44-a308-7662fec0f546",
        "name": "Bitcoin",
        "type": "Crypto",
        "code": "BTC"
      },
      "quantity": "0.5"
    },
    "proceeds": {

      "asset": {

        "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
        "name": "United States Dollar",
        "type": "Fiat",
        "code": "USD"
      },
      "quantity": "30000"
    },
    "gain_type": "short-term",
    "tax_year": "2024",
    "user_id": "6a33f4fa-f9cf-445e-ae59-496c4bde213a",
    "index": "lot-id=c8627a07-3492-5e91-827d-94d4094240b0,fee=false",
    "acquisition_transaction_id": "dc909d4d-d500-5d27-8cd5-e2a41a74a75a",
    "disposition_transaction_id": "15955016-a10b-5fcd-9e65-3af6d0cf6a09",
    "update_time": "2024-07-02T19:23:13.402419Z",
    "gain": {

      "asset": {

        "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
        "name": "United States Dollar",
        "type": "Fiat",
        "code": "USD"
      },
      "quantity": "19997.5"
    },
    "cost": {

      "asset": {

        "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
        "name": "United States Dollar",
        "type": "Fiat",
        "code": "USD"
      },
      "quantity": "10002.5"
    },
    "cost_basis_date": "2024-01-01T12:13:14.123Z"
  }
]