Build tax center experiences

A tax center shows users the tax side of their activity inside your app: 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; Real-time inventory, Display unrealized gain/loss, and Tax loss harvesting go deeper.

By the end of this page you know which call powers each part of a tax center and how to keep its figures current.

Before you begin

• A bearer token. See Authenticate your tenant.
• Transactions flowing for your users' accounts. See Set up inventory and gains.
• A current price for each asset you show, from your own platform, so the figures match the prices users 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, or compare the latest transaction the inventory reflects with the latest one you sent. Real-time inventory 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. Display unrealized gain/loss 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 users harvest losses

Combine lot-level inventory with your prices to find lots that would sell at a loss, show them to the user, and send the sale with SPECID so it draws from exactly the lots the user picked. Tax loss harvesting walks through the sequence.

Where to go next

• Real-time inventory, first, so every screen reads current figures.
• SLAs & async behavior: how quickly inventory reflects a new transaction.