---
title: "Log a capital-gains trade"
method: POST
path: "/api/v1/trades"
tags: ["Capital Gains"]
---

# Log a capital-gains trade

`POST /api/v1/trades`

## Request

- Base URL: `https://www.agenttax.io`
- URL: `https://www.agenttax.io/api/v1/trades`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-PAYMENT`

Records a buy/sell with FIFO/LIFO/Specific-ID cost basis. Wash-sale detection runs automatically (api/_lib/wash-sale.js). Also discoverable via x402 (POST without auth + X-PAYMENT header returns a preview without writing).

## Request body

- TradeRequest
  - `asset_symbol` string, required: Asset ticker — equity (AAPL), crypto (BTC), or token (COMPUTE-TOKEN). Auto-uppercased.
  - `trade_type` 'buy' | 'sell', required
  - `quantity` number, required
  - `price_per_unit` number, required
  - `fee_amount` number
  - `trade_date` string, date-time: ISO 8601 trade timestamp. Defaults to server time when omitted.
  - `accounting_method` 'fifo' | 'lifo' | 'specific_id'
  - `specific_lot_id` string, nullable: Required when accounting_method='specific_id'. Identifies which cost-basis lot to consume.
  - `asset_name` string
  - `counterparty` string
  - `exchange` string
  - `notes` string
  - `resident_state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'DC': Two-letter resident state code used for state capital-gains estimation.
  - `tax_entity_type` 'individual' | 'c_corp' | 'pass_through': Entity classification for federal estimation.
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh': Federal filing status used to pick the income-tax / LT-capital-gains bracket.
  - `estimated_annual_income` number: Estimated annual income; enables bracket-aware federal estimation and NIIT detection.
  - `asset_class` 'stock' | 'security' | 'securities' | 'equity' | 'digital_asset' | 'crypto': Opt into IRC §1091 wash-sale tracking. 'stock'/'security'/'securities'/'equity' enable detection; 'digital_asset'/'crypto'/omitted disable it (digital assets are not subject to §1091 under current Treasury guidance).

## Response `200`

Trade logged with realized gain/loss if SELL.

## Other responses

- `400`: Validation failure
- `401`: Authentication required
- `402`: x402 payment required for unauthenticated callers

---

[API](https://skmtc.dev/agenttax/apis/agenttax-api.md) · [All operations](https://skmtc.dev/agenttax/apis/agenttax-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agenttax/apis/agenttax-api/revisions/c4af8147c0cb?raw)