# PaperTax

> PaperTax turns a public Hyperliquid wallet address into tax-ready records: realised gains and losses, liquidations, fees and funding for Hyperliquid perps and every HIP-3 builder market, plus spot, HLP and vaults, HYPE staking and transfers (trade.xyz, Paragon, Felix, Ventuals, Kinetiq and others), with Koinly and Crypto Tax Calculator CSV exports. Papertrade on HyperEVM is read live: closes, liquidations, PAPER mints, staking and queued profits. Read-only: it never asks for keys or signatures.

Key facts:
- Tax years: AU-2026 / AU-2027 (Australia, 1 Jul–30 Jun; FY 2025-26 due 31 Oct 2026 for self-lodgers), US-2025 / US-2026 (calendar), UK-2026 / UK-2027 (6 Apr–5 Apr; 2025-26 due 31 Jan 2027), CA-2025 / CA-2026 (calendar; due 30 Apr), NZ-2026 / NZ-2027 (1 Apr–31 Mar; IR3 due 7 Jul). UK, Canada and NZ defaults are new and awaiting local professional review. Amounts are in USD (USDC); convert to local currency.
- Classifications are defaults for review, not tax advice. Funding payments, tokens minted on a loss (e.g. PAPER) and queued profits have no settled treatment and are flagged.
- Also covered: Hyperliquid spot trades (exported as trades; PaperTax shows Hyperliquid's average-cost result as an estimate), HLP and other vault deposits and withdrawals (gain or loss against Hyperliquid's reported cost basis), HYPE staking rewards (valued at the daily HYPE close), referral rewards, vault leader commissions, airdrops, and deposits, withdrawals and transfers (listed, not taxable; fees kept as costs).
- HyperEVM wallet: bridges, Kinetiq / StakedHYPE / Looped HYPE / HyperLend / Felix deposits and withdrawals, swaps, tokens received and gas, read from on-chain history. Swaps and protocol moves export as trades; unclear items are flagged. Contracts that copy Papertrade are detected and their deposits and withdrawals listed.
- Updates and support: X [@papertaxdev](https://x.com/papertaxdev), email nick@astrnt.me.
- Pricing (USD): Preview free (summary, journal, first 10 ledger rows). Tax report per wallet per tax year: $29 (≤500 events), $59 (≤5,000), $99 (unlimited), no account needed. Trader $99/year or $12/month (10 wallets, API). Accountant $59 per client per year, $39 from 25 clients.

## Use it from an agent

- [MCP server](https://papertax.xyz/mcp): Streamable HTTP, POST JSON-RPC. Tools: `get_tax_summary` (free), `get_ledger_events`, `export_tax_file`, `explain_tax_treatment`. All read-only. Take `tax_year` (e.g. `AU-2026`).
- Auth: `Authorization: Bearer ptx_…` (API key from https://papertax.xyz/account, Trader or Accountant plan). Without paid access, live wallets get a preview and an unlock link; `sample: true` is always free.
- Buying: `buy_report` (MCP; listed when you connect with an API key or to `https://papertax.xyz/mcp?tools=all`) or `POST /api/buy`. Card: `{"address","tax_year","method":"card","max_price_cents"?}` with an API key, charged to the owner's saved card if they switched agent purchases on. USDC on HyperEVM (no account): `{"address","tax_year","method":"usdc"}` returns a quote; send exactly that USDC amount on chain 999 to the given address, then `{"quote_id","tx_hash"}`. Both return an unlock token and export links (`&unlock=` works on /api/export).
- x402 (USDC on Base or Solana, one request, no account): `GET /api/buy?address=0x…&year=AU-2026` answers 402 with x402 payment requirements (v2 `PAYMENT-REQUIRED` header; v1 `accepts` in the body). Retry with `PAYMENT-SIGNATURE` (or `X-PAYMENT`) to pay; the response has the unlock token and export links, plus `PAYMENT-RESPONSE`. `GET /api/export` works the same way and returns the file itself, with the unlock token in `x-papertax-unlock`.
- Audit pack: export format `audit` (JSON: every figure with its transaction hash and explorer link, rules version, data fingerprint, reconciliation) or `auditpdf` (printable PDF).
- [Server card](https://papertax.xyz/mcp/server-card) and [server.json](https://github.com/AwakeWeb3/papertax/blob/main/server.json).
- [OpenAPI spec](https://papertax.xyz/openapi.json): HTTP endpoints below.
- `POST /api/ledger` with `{"address": "0x…", "year": "AU-2026"}`: ledger as JSON, plus `access` (can this caller export it, and the price if not).
- `GET /api/export?address=0x…&format=koinly|ctc|summary|audit|auditpdf&year=AU-2026`: the export file (402 with an unlock link if not paid). Add `&sample=1` for sample data.

## Data sources

- Hyperliquid Info API (public): `userFillsByTime`, `userFunding`, `clearinghouseState`, `perpDexs`. Fills from one order are merged; funding is summed per market per UTC day.
- HIP-3 markets are identified by the `dex:` prefix on coin names (e.g. `xyz:TSLA`).

## Optional

- [Website](https://papertax.xyz/): interactive ledger, journal, year-end check and exports.
- Independent tool; not affiliated with Hyperliquid, trade.xyz, Paragon, Papertrade, Koinly or Crypto Tax Calculator.

## Guides

- [Hyperliquid tax in Australia](https://papertax.xyz/guides/hyperliquid-tax-australia): FY 2025-26, capital vs revenue, funding, records.
- [Hyperliquid taxes in the US](https://papertax.xyz/guides/hyperliquid-tax-us): no 1099, Section 1256, Form 8949.
- [Papertrade tax records](https://papertax.xyz/guides/papertrade-tax): closes, liquidations, PAPER mints, staking, queued profits.
- [HIP-3 markets](https://papertax.xyz/guides/hip-3-tax): trade.xyz, Paragon, Felix; stock and commodity perps.
- [Import into Koinly or Crypto Tax Calculator](https://papertax.xyz/guides/hyperliquid-koinly-crypto-tax-calculator): CSV steps, avoiding duplicates.
- [Best Hyperliquid tax software](https://papertax.xyz/guides/best-hyperliquid-tax-software): PaperTax, Koinly, Awaken, CTC and others, with picks by situation.
- [PaperTax vs Koinly for Hyperliquid](https://papertax.xyz/guides/papertax-vs-koinly-hyperliquid): differences and how to use both together.
- [Hyperliquid tax in the UK](https://papertax.xyz/guides/hyperliquid-tax-uk): HMRC guidance, pooling, sterling values.
- [Hyperliquid tax in Canada](https://papertax.xyz/guides/hyperliquid-tax-canada): capital vs business income, ACB, superficial losses.
- [Hyperliquid tax in New Zealand](https://papertax.xyz/guides/hyperliquid-tax-new-zealand): income treatment, IRD DeFi view, NZD values.