Consuming Gains
Taxbit also has Gains endpoints to consume information on specific account's disposals and relevant Gains (or Losses).
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"
}
]
Updated 5 months ago