Consuming Inventory

Once the transaction is processed, you can fetch inventory for a given account_id – your system's unique identifier for the Account object.

/v1/inventory

Requests to /v1/inventory return both the summary and lots for a given asset. Immediately following the above purchase, the account has a single lot in inventory with a cost of $20,005 (the purchase price plus fee):

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": "1",
      "total_cost": "20005",
      "average_unit_cost": "20005",
      "total_quantity_with_cost_basis": "1"
    },
    "lots": [
      {
        "id": "c8627a07-3492-5e91-827d-94d4094240b0",
        "acquisition_datetime": "2024-01-01T12:13:14.123Z",
        "term": "short-term",
        "quantity": "1",
        "fiat_asset_code": "USD",
        "cost": "20005",
        "unit_cost": "20005"
      }
    ]
  }
}

/v1/inventory/summaries

Requests to /inventory/summaries return summary-level detail for each asset held in inventory. Let’s extend the above example to buy another bitcoin (for $40,000) and a single Ethereum token for $2,000.

First, let’s add another transaction to acquire the Bitcoin by calling /transactions/external-id

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": "2",
    "datetime": "2024-01-02T12:13:14.123Z",
    "type": "trade",
    "fees": [
        {
            "asset_amount": {
                "amount": "5.00",
                "asset": {
                    "code": "USD",
                    "type": "fiat"
                }
            },
            "rates": [
                {
                    "amount": "1.00",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    }
                }
            ]
        }
    ],
    "received": [
        {
            "asset_amount": {
                "amount": "1.00",
                "asset": {
                    "code": "BTC",
                    "type": "crypto"
                }
            },
            "rates": [
                {
                    "amount": "40000.00",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    }
                }
            ]
        }
    ],
    "sent": [
        {
            "asset_amount": {
                "amount": "40000.00",
                "asset": {
                    "code": "USD",
                    "type": "fiat"
                }
            },
            "rates": [
                {
                    "amount": "1.00",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    }
                }
            ]
        }
    ],
    "version": "2.0"
}'

Now make a second request to /transactions/external-id to acquire ETH:

curl --request POST \
  --url https://api.multi1.enterprise.taxbit.com/v1/transactions/external-id \
  --header 'authorization: Bearer {{token}}' \
  --header 'content-type: application/json' \
  --header 'user-agent: vscode-restclient' \
  --data '{
    "account_id": "{{acount-id}}",
    "id": "3",
    "datetime": "2024-01-03T12:13:14.123Z",
    "type": "trade",
    "fees": [
        {
            "asset_amount": {
                "amount": "5.00",
                "asset": {
                    "code": "USD",
                    "type": "fiat"
                }
            },
            "rates": [
                {
                    "amount": "1.00",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    }
                }
            ]
        }
    ],
    "received": [
        {
            "asset_amount": {
                "amount": "1.00",
                "asset": {
                    "code": "ETH",
                    "type": "crypto"
                }
            },
            "rates": [
                {
                    "amount": "2000.00",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    }
                }
            ]
        }
    ],
    "sent": [
        {
            "asset_amount": {
                "amount": "2000.00",
                "asset": {
                    "code": "USD",
                    "type": "fiat"
                }
            },
            "rates": [
                {
                    "amount": "1.00",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    }
                }
            ]
        }
    ],
    "version": "2.0"
}
'

Now a request to /inventory/summaries will return a summarized view of all the assets for the given account (both BTC and ETH)

curl --request GET \
  --url 'https://api.multi1.enterprise.taxbit.com/v1/inventory/summaries?account_id={{account-id}}' \
  --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": "2",
        "total_cost": "60010",
        "average_unit_cost": "30005",
        "total_quantity_with_cost_basis": "2"
      }
    },
    {
      "asset": {
        "uuid": "b7a005b5-f4d5-44ea-ae80-d4f9e8313558",
        "name": "Ethereum",
        "code": "ETH",
        "type": "Crypto"
      },
      "fiat_asset": {
        "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
        "name": "United States Dollar",
        "code": "USD",
        "type": "Fiat"
      },
      "summary": {
        "total_quantity": "1",
        "total_cost": "2005",
        "average_unit_cost": "2005",
        "total_quantity_with_cost_basis": "1"
      }
    }
  ]
}

And call /inventory/ to see the bitcoin-specific inventory with two lots:

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": "2",
      "total_cost": "60010",
      "average_unit_cost": "30005",
      "total_quantity_with_cost_basis": "2"
    },
    "lots": [
      {
        "id": "bb694f5c-d2ef-5ff9-82cc-a73ace56db0c",
        "acquisition_datetime": "2024-01-02T12:13:14.123Z",
        "term": "short-term",
        "quantity": "1",
        "fiat_asset_code": "USD",
        "cost": "40005",
        "unit_cost": "40005"
      },
      {
        "id": "c8627a07-3492-5e91-827d-94d4094240b0",
        "acquisition_datetime": "2024-01-01T12:13:14.123Z",
        "term": "short-term",
        "quantity": "1",
        "fiat_asset_code": "USD",
        "cost": "20005",
        "unit_cost": "20005"
      }
    ]
  }
}

Each previous transaction acquired a crypto asset in the context of a fiat price captured in the transaction’s rates keys, which serves as a cost basis for the lot. Sometimes lots are acquired without an available cost basis. For example, the following POST requests will create a deposit transaction for 10 Solana tokens:

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": "42",
    "datetime": "2023-01-01T00:00:00.000Z",
    "type": "deposit",
    "version": "1.0",
    "received": [
        {
            "asset_amount": {
                "amount": "10",
                "asset": {
                    "code": "SOL",
                    "type": "crypto"
                }
            }
        }
    ]
}'

Querying SOL via /v1/inventory returns a lot without a unit_cost, with the entire quantity included in the summary.total_quantity_missing_cost_basis field:

curl --request GET \
  --url 'https://api.multi1.enterprise.taxbit.com/v1/inventory?account_id={{account-id}}&asset_code=SOL' \
  --header 'authorization: Bearer {{token}}'

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

{
  "data": {
    "asset": {
      "uuid": "b27b2831-577d-4067-bebe-44fba24da70e",
      "name": "Solana",
      "code": "SOL",
      "type": "Crypto"
    },
    "fiat_asset": {
      "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396",
      "name": "United States Dollar",
      "code": "USD",
      "type": "Fiat"
    },
    "summary": {
      "total_quantity": "10",
      "total_cost": "0",
      "average_unit_cost": "0",
      "total_quantity_with_cost_basis": "0",
      "total_quantity_missing_cost_basis": "10"
    },
    "lots": [
      {
        "id": "06c17794-3520-5338-bbc1-95355c009248",
        "acquisition_datetime": "2023-01-01T00:00:00Z",
        "term": "long-term",
        "quantity": "10",
        "fiat_asset_code": "USD"
      }
    ]
  }
}