Retrieve gains

Part of Send transactions and read 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.

Before you begin

• A bearer token. See Authenticate.
• Transactions sent for the account, including at least one disposal, as in Send transactions and read 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. /v1/gains/breakdown also works without them and then covers 2009-01-01 through now.

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 cost-basis methods (disposition_method), 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 cost-basis method recalculates gains. A backdated method change recalculates gains from its effective date forward, typically within a few seconds; this is observed timing, not an SLA. 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. Request a new one and retry.
• 429. Too many requests. Slow down and retry.

The Errors and rate limits page has every error shape, the rate limits, and which calls are safe to 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 cost-basis method: how the method decides which lot a sale draws from.
• Show tax data in your app: show these figures to your account owners.
• Back to Send transactions and read gains.