Show tax data in your app

Tax screens in your app show account owners the tax side of their activity: what they hold and what it cost, what they would gain or lose by selling at today's price, what they have already realized this year, and which lots they could sell at a loss. Every figure comes from the same inventory and gains endpoints the rest of this section uses, combined with prices from your own platform.

This walkthrough spans four pages. This one lays out the screens and the calls behind them; Refresh inventory by webhook or polling, Show unrealized gains and losses, and Support tax-loss harvesting go deeper.

Before you begin

• A bearer token. See Authenticate.
• Transactions flowing for your account owners' accounts. See Send transactions and read gains.
• A current price for each asset you show, from your own platform, so the figures match the prices account owners see elsewhere in your app.

Keep the figures current

Inventory recalculates in the background after each transaction, so read it after it has caught up. Subscribe to the INVENTORY_UPDATE webhook and refresh an account's figures when its event arrives, and poll as a fallback; delivery is not guaranteed after every write. To poll, compare the latest transaction the inventory reflects with the latest one you sent. See how to know when figures are current. Refresh inventory by webhook or polling shows both.

Show holdings and cost basis

For a portfolio screen, call GET /v1/inventory/summaries with the account_id: one entry per asset, with its total quantity, total cost, and average unit cost. For one asset's detail screen, call GET /v1/inventory with the asset_code to list its open lots, each with its acquisition date, term, quantity, and cost. Retrieve inventory has both requests.

Show unrealized gain or loss

Pass your current price for the asset to GET /v1/inventory as price, and the response adds the current value and the unrealized gain or loss, for the asset as a whole and for each lot. Deposits without a cost basis need a display decision. Show unrealized gains and losses covers the fields and the choices.

Show realized gains for a period

For year-to-date figures, call GET /v1/gains/breakdown with start_date set to January 1 and end_date set to now, both as full datetimes, for short-term, long-term, and total gains. For the list of sales behind them, call GET /v1/gains. Retrieve gains has both requests.

Help account owners harvest losses

Combine lot-level inventory with your prices to find lots that would sell at a loss, show them to the account owner, and send the sale with SPECID (specific identification) so it draws from exactly the lots the account owner picked. Support tax-loss harvesting walks through the sequence.

Where to go next

• Refresh inventory by webhook or polling, first, so every screen reads current figures.
• Know when inventory and gains are current: how quickly inventory reflects a new transaction.