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 about 1 month ago