Retrieve gains

Part of Set up inventory and gains. A gain or loss is realized when an account disposes of an asset: the proceeds minus the cost of the lots the disposal drew from. This page reads those results back in three shapes: one row per disposition, totals by term, and totals by asset.

By the end of this page you can list an account's dispositions for a tax year with their gains, total them into short-term and long-term, and summarize them per asset.

Before you begin

• A bearer token. See Authenticate your tenant.
• Transactions sent for the account, including at least one disposal, as in Set up inventory and gains. The examples continue that walkthrough: 2.5 ETH bought in February for $3,250 each, 1 ETH sold in July for $3,000.

Every gains endpoint takes start_date and end_date as full ISO 8601 datetimes, such as 2026-01-01T00:00:00Z. A date-only value such as 2026-01-01 returns 400.

Get each disposition

GET /v1/gains returns one record per disposition in the period.

curl -G $BASE_URL/v1/gains \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "account_id=acct_5f2e7d10" \
  --data-urlencode "start_date=2026-01-01T00:00:00Z" \
  --data-urlencode "end_date=2026-12-31T23:59:59Z"

{
  "data": [
    {
      "sale_date": "2026-07-15T13:05:40Z",
      "cost_basis_date": "2026-02-14T16:20:11Z",
      "gain_type": "short-term",
      "amount_sold": {
        "asset": { "code": "ETH", "name": "Ethereum", "type": "Crypto", "uuid": "b7a005b5-f4d5-44ea-ae80-d4f9e8313558" },
        "quantity": "1"
      },
      "proceeds": {
        "asset": { "code": "USD", "name": "US Dollar", "type": "Fiat", "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396" },
        "quantity": "3000.00"
      },
      "cost": {
        "asset": { "code": "USD", "name": "US Dollar", "type": "Fiat", "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396" },
        "quantity": "3250.00"
      },
      "gain": {
        "asset": { "code": "USD", "name": "US Dollar", "type": "Fiat", "uuid": "df939ab7-b7ed-4216-be63-ca1d2a130396" },
        "quantity": "-250.00"
      },
      "client_acquisition_transaction_id": "trade_88213",
      "client_disposition_transaction_id": "trade_88214"
    }
  ]
}

Under the standard disposition methods, gain_type is short-term or long-term, by how long the lot was held. client_acquisition_transaction_id and client_disposition_transaction_id tie each record back to the transactions you sent. When there are more records than fit in one page, the response carries a continuation_key; pass it back to get the next page, and set the page length with page_size.

Get totals by term

GET /v1/gains/breakdown totals the period into short-term, long-term, and overall figures. Pass both dates to scope the results to a tax year.

curl -G $BASE_URL/v1/gains/breakdown \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "account_id=acct_5f2e7d10" \
  --data-urlencode "start_date=2026-01-01T00:00:00Z" \
  --data-urlencode "end_date=2026-12-31T23:59:59Z"

The response carries short_term, long_term, and total, each an asset and a quantity. For this account, the July sale puts a $250 loss in short_term and total.

Get totals by asset

GET /v1/gains/summary returns one summary per asset disposed of in the period: total_quantity disposed, total_cost, total_proceeds_with_cost_basis, and total_gains_count, among others.

curl -G $BASE_URL/v1/gains/summary \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "account_id=acct_5f2e7d10" \
  --data-urlencode "start_date=2026-01-01T00:00:00Z" \
  --data-urlencode "end_date=2026-12-31T23:59:59Z"

Gains move when the inventory changes

Backfilling older transactions or changing the disposition method recalculates gains. A backdated method change recalculates gains from its effective date forward within about three seconds. Do not cache gains across a backfill or a method change; read them again afterwards.

If the request fails

• 400. A parameter is invalid. The most common cause is a date without a time: Query param 'start_date' must be a valid datetime.
• 401. The bearer token is missing, invalid, or expired. Mint a new one and retry.
• 429. Too many requests. Slow down and retry.

Parameters

Only the parameters used above. The full lists are in the Get gains, Get gains breakdown, and Get gains summary references.

Where to go next

• Choose a disposition method: how the method decides which lot a sale draws from.
• Build tax center experiences: show these figures to your users.
• Back to Set up inventory and gains.