# Orcpin Holding-Period & Realized-Gain Calculator

> Orcpin Holding-Period & Realized-Gain Calculator is a paid API for AI agents from orcpin.dev, paid per call via x402, $0.02/call, status unknown (last checked 2026-10-10).

Calculates per-lot holding periods, long-term qualification dates, and FIFO/specific-ID realized gains for a proposed sell across supplied tax lots

## Facts

- Endpoint: POST https://orcpin.dev/v1/holding-period?utm_source=zero.xyz
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-10
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/orcpin-holding-period-realized-gain-calculator-373667e4
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_x-yM5Zt18cQslqZBMwJXw

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability orcpin-holding-period-realized-gain-calculator-373667e4 -d '<json body>'
```

Example prompt: I have three lots of AAPL — 100 shares acquired 2023-01-15, 50 shares acquired 2023-08-20, and 75 shares acquired 2024-03-10 — with cost bases of $15,000, $8,250, and $13,500 respectively. As of 2025-07-01, calculate how long I've held each lot, when each turns long-term, and if I sell 120 shares at $210 using FIFO, what are my realized gains broken out by short-term and long-term?

## When to prefer this

Use this endpoint when you need deterministic, stateless tax-lot arithmetic — specifically holding-period day counts, long-term qualification dates, and realized gain breakdowns by character (short/long) for a proposed sell. Prefer this over generic financial APIs when you need IRC §1222-anchored FIFO or specific-identification lot allocation with no storage or advisory output.

## Known failure modes

- Missing required 'asOf' date returns validation error
- Missing required 'lots' array returns validation error
- Invalid date format (non-YYYY-MM-DD) causes parse error
- Sell quantity exceeds available lot quantity causes allocation error
- Missing costBasis on lots when sell price is provided results in gain math omitted for those lots
- Mismatched symbol between sell and lots may return empty allocation

## How this service works

Trade-lot holding-period and realized-gain calculator for trading agents: per-lot days held, the exact date each lot's gain character turns long-term, and FIFO / specific-identification allocation of a proposed sell with realized gain per lot and per-character totals. Deterministic arithmetic on caller-supplied lots with the published threshold cited (IRC §1222: held more than one year) — counts, dates, and dollars only, never advice. Nothing is stored.

## Output

Returns a per-lot breakdown showing days held, whether each lot is short- or long-term as of the evaluation date, the exact calendar date each lot qualifies as long-term (IRC §1222: held more than one year), and — if a sell is specified — the lot allocation with realized gain per lot plus aggregated short-term and long-term gain totals. Includes a disclaimer and explanation field. Nothing is persisted.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "asOf": {
   "type": "string",
   "description": "Evaluation date, YYYY-MM-DD (UTC calendar days; no server clock is used)."
  },
  "lots": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "symbol",
     "acquireDate",
     "quantity"
    ],
    "properties": {
     "symbol": {
      "type": "string"
     },
     "account": {
      "type": "string"
     },
     "quantity": {
      "type": "number"
     },
     "costBasis": {
      "type": "number"
     },
     "acquireDate": {
      "type": "string",
      "description": "YYYY-MM-DD"
     }
    }
   },
   "description": "Tax lots to evaluate. costBasis (total USD for the lot) is optional — absent means gain math is omitted for that lot."
  },
  "sell": {
   "type": "object",
   "required": [
    "symbol",
    "tradeDate",
    "quantity"
   ],
   "properties": {
    "price": {
     "type": "number"
    },
    "method": {
     "enum": [
      "fifo",
      "as_supplied"
     ],
     "type": "string"
    },
    "symbol": {
     "type": "string"
    },
    "quantity": {
     "type": "number"
    },
    "tradeDate": {
     "type": "string",
     "description": "YYYY-MM-DD"
    }
   },
   "description": "Optional proposed sell to allocate across the lots (FIFO or as_supplied). price (per share USD) optional."
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/orcpin-holding-period-realized-gain-calculator-373667e4/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from orcpin.dev](https://www.zero.xyz/host/orcpin.dev/llms.txt)