buy_report

Buy the full report for one wallet and tax year ($29 up to 500 events, $59 up to 5,000, $99 above; upgrades charge the difference). method "card" charges the account owner's saved card: needs Authorization: Bearer ptx_… and the owner's opt-in; set max_price_cents to cap it. method "usdc" returns a quote: send exactly that USDC amount on HyperEVM (chain 999) to the given address, then call again with quote_id and tx_hash. (x402 clients can instead pay in USDC on Base or Solana at GET https://papertax.xyz/api/buy?address=…&year=….) Returns an unlock_token and export links. This spends money: confirm with the user first.

Argument	Type	Description
method	string
address	string	Public Hyperliquid wallet address
tx_hash	string	USDC step 2: the HyperEVM transaction hash of the transfer
quote_id	string	USDC step 2: the quote_id from step 1
tax_year	string	Tax year. AU-2027 = Australia · FY 2026–27; AU-2026 = Australia · FY 2025–26; US-2026 = United States · 2026; US-2025 = United States · 2025; UK-2027 = United Kingdom · 2026–27; UK-2026 = United Kingdom · 2025–26; CA-2026 = Canada · 2026; CA-2025 = Canada · 2025; NZ-2027 = New Zealand · 2026–27; NZ-2026 = New Zealand · 2025–26; JP-2026 = Japan · 2026; JP-2025 = Japan · 2025; ES-2026 = Spain · 2026; ES-2025 = Spain · 2025. Defaults by jurisdiction: AU AU-2026, US US-2026, UK UK-2026, CA CA-2026, NZ NZ-2027, JP JP-2026, ES ES-2026.
max_price_cents	integer	Card only: refuse if the price is higher than this

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "method": {
      "enum": [
        "card",
        "usdc"
      ],
      "type": "string",
      "default": "card"
    },
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Public Hyperliquid wallet address"
    },
    "tx_hash": {
      "type": "string",
      "description": "USDC step 2: the HyperEVM transaction hash of the transfer"
    },
    "quote_id": {
      "type": "string",
      "description": "USDC step 2: the quote_id from step 1"
    },
    "tax_year": {
      "enum": [
        "AU-2027",
        "AU-2026",
        "US-2026",
        "US-2025",
        "UK-2027",
        "UK-2026",
        "CA-2026",
        "CA-2025",
        "NZ-2027",
        "NZ-2026",
        "JP-2026",
        "JP-2025",
        "ES-2026",
        "ES-2025"
      ],
      "type": "string",
      "description": "Tax year. AU-2027 = Australia · FY 2026–27; AU-2026 = Australia · FY 2025–26; US-2026 = United States · 2026; US-2025 = United States · 2025; UK-2027 = United Kingdom · 2026–27; UK-2026 = United Kingdom · 2025–26; CA-2026 = Canada · 2026; CA-2025 = Canada · 2025; NZ-2027 = New Zealand · 2026–27; NZ-2026 = New Zealand · 2025–26; JP-2026 = Japan · 2026; JP-2025 = Japan · 2025; ES-2026 = Spain · 2026; ES-2025 = Spain · 2025. Defaults by jurisdiction: AU AU-2026, US US-2026, UK UK-2026, CA CA-2026, NZ NZ-2027, JP JP-2026, ES ES-2026."
    },
    "max_price_cents": {
      "type": "integer",
      "minimum": 0,
      "description": "Card only: refuse if the price is higher than this"
    }
  },
  "additionalProperties": false
}

create_verified_pnl

Read a wallet's results for one tax year from the chain and return a public, signed link (https://papertax.xyz/v/…) with a share image, for posting on X or anywhere else. Free, and nothing is stored. Dollar amounts are included only when amounts is true. With private true (the default) the wallet address is left out of the link and the page; with private false the page shows it, so check with the user first. It proves what the wallet did, not who owns it.

read-only

Argument	Type	Description
address*	string	Public Hyperliquid wallet address
amounts	boolean	Include net result, gains, losses and fees
private	boolean	Leave the wallet address out of the link and page
tax_year	string	Tax year. AU-2027 = Australia · FY 2026–27; AU-2026 = Australia · FY 2025–26; US-2026 = United States · 2026; US-2025 = United States · 2025; UK-2027 = United Kingdom · 2026–27; UK-2026 = United Kingdom · 2025–26; CA-2026 = Canada · 2026; CA-2025 = Canada · 2025; NZ-2027 = New Zealand · 2026–27; NZ-2026 = New Zealand · 2025–26; JP-2026 = Japan · 2026; JP-2025 = Japan · 2025; ES-2026 = Spain · 2026; ES-2025 = Spain · 2025. Defaults by jurisdiction: AU AU-2026, US US-2026, UK UK-2026, CA CA-2026, NZ NZ-2027, JP JP-2026, ES ES-2026.
jurisdiction	string	Used when tax_year is not given. AU = 1 Jul–30 Jun; US, CA, JP and ES = calendar year; UK = 6 Apr–5 Apr; NZ = 1 Apr–31 Mar

explain_tax_treatment

papertax's default treatment notes for Australia, the US, the UK, Canada, New Zealand, Japan or Spain, optionally for one event type. Not tax advice.

read-only

Argument	Type	Description
event_type	string
jurisdiction	string	Used when tax_year is not given. AU = 1 Jul–30 Jun; US, CA, JP and ES = calendar year; UK = 6 Apr–5 Apr; NZ = 1 Apr–31 Mar

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "event_type": {
      "enum": [
        "loss",
        "liq",
        "gain",
        "queued",
        "funding",
        "mint",
        "stakepay",
        "spotgain",
        "spotloss",
        "vaultgain",
        "vaultloss",
        "income",
        "airdrop",
        "xfer",
        "evmswap",
        "defiin",
        "defiout",
        "receive"
      ],
      "type": "string"
    },
    "jurisdiction": {
      "enum": [
        "AU",
        "US",
        "UK",
        "CA",
        "NZ",
        "JP",
        "ES"
      ],
      "type": "string",
      "default": "AU",
      "description": "Used when tax_year is not given. AU = 1 Jul–30 Jun; US, CA, JP and ES = calendar year; UK = 6 Apr–5 Apr; NZ = 1 Apr–31 Mar"
    }
  },
  "additionalProperties": false
}

export_tax_file

Koinly universal CSV, Crypto Tax Calculator advanced CSV, Cryptact custom file (JST, priced in yen by Cryptact), plain-text accountant summary, or the audit pack (audit = JSON with every figure tied to its transaction hash, a rules version and a data fingerprint; auditpdf = the printable PDF). Live wallets need paid access (API key or paid report). Large files are cut short with a download link.

Argument	Type	Description
format	string
sample	boolean	Return deterministic sample data instead of reading Hyperliquid
address*	string	Public Hyperliquid wallet address
tax_year	string	Tax year. AU-2027 = Australia · FY 2026–27; AU-2026 = Australia · FY 2025–26; US-2026 = United States · 2026; US-2025 = United States · 2025; UK-2027 = United Kingdom · 2026–27; UK-2026 = United Kingdom · 2025–26; CA-2026 = Canada · 2026; CA-2025 = Canada · 2025; NZ-2027 = New Zealand · 2026–27; NZ-2026 = New Zealand · 2025–26; JP-2026 = Japan · 2026; JP-2025 = Japan · 2025; ES-2026 = Spain · 2026; ES-2025 = Spain · 2025. Defaults by jurisdiction: AU AU-2026, US US-2026, UK UK-2026, CA CA-2026, NZ NZ-2027, JP JP-2026, ES ES-2026.
save_wallet	boolean	With a Trader or Accountant plan API key: add this wallet to the plan if it is not on it yet (uses one of the plan's 10 wallets or a client seat). Without it, a wallet not on the plan gets the preview and a note.
jurisdiction	string

get_games

How papertax games work (Edge, Climb, and 1v1 and Pit rooms on real papertrade positions, with crews and weekly leaderboards), this week's boards (top 10 players or crews; players show as their X account, papertrade name or wallet), open and live rooms, and the Bulls vs Bears tally. Read-only; playing needs the website and a wallet, and games open when trading on papertax goes live.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

get_ledger_events

Individual ledger rows with default tax classification: perp opens, closes, liquidations and funding; spot buys and sells; vault deposits and withdrawals; staking rewards; HyperEVM swaps and protocol deposits; transfers; papertrade mints and staking. Filter by event type or venue. Without paid access, live wallets return the first 10 rows.

Argument	Type	Description
type	string
limit	integer
venue	string	Venue key: hl (perps), hip3:<dex> (e.g. hip3:xyz), spot, vault, staking, evm (HyperEVM), pt (papertrade), fork, core (deposits and transfers)
sample	boolean	Return deterministic sample data instead of reading Hyperliquid
address*	string	Public Hyperliquid wallet address
tax_year	string	Tax year. AU-2027 = Australia · FY 2026–27; AU-2026 = Australia · FY 2025–26; US-2026 = United States · 2026; US-2025 = United States · 2025; UK-2027 = United Kingdom · 2026–27; UK-2026 = United Kingdom · 2025–26; CA-2026 = Canada · 2026; CA-2025 = Canada · 2025; NZ-2027 = New Zealand · 2026–27; NZ-2026 = New Zealand · 2025–26; JP-2026 = Japan · 2026; JP-2025 = Japan · 2025; ES-2026 = Spain · 2026; ES-2025 = Spain · 2025. Defaults by jurisdiction: AU AU-2026, US US-2026, UK UK-2026, CA CA-2026, NZ NZ-2027, JP JP-2026, ES ES-2026.
save_wallet

get_papertrade_positions

Free, read-only. A wallet's papertrade (BTC and ETH perps on HyperEVM) balance and open positions: market, side, leverage, margin, entry, current price, liquidation price and how far away it is, and what each would keep if closed now, after papertrade's impact haircut and 2% win fee. Answers "how are my positions doing?". Closing or opening needs the wallet's signature on papertax.xyz.

read-only

Argument	Type	Description
address*	string	Public Hyperliquid wallet address

Input schema (JSON)

{
  "type": "object",
  "required": [
    "address"
  ],
  "properties": {
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Public Hyperliquid wallet address"
    }
  },
  "additionalProperties": false
}

get_papertrade_results

Free, read-only. What a wallet kept from papertrade closes over a period (default the last 30 days): closes, wins, losses, liquidations, win fees paid, PAPER minted, by market, and the best and worst trade. Answers "what did I keep this month?".

read-only

Argument	Type	Description
to	string	End date, YYYY-MM-DD (UTC), inclusive; defaults to today
days	integer	Look back this many days (ignored when from is given)
from	string	Start date, YYYY-MM-DD (UTC)
address*	string	Public Hyperliquid wallet address

Input schema (JSON)

{
  "type": "object",
  "required": [
    "address"
  ],
  "properties": {
    "to": {
      "type": "string",
      "format": "date",
      "description": "End date, YYYY-MM-DD (UTC), inclusive; defaults to today"
    },
    "days": {
      "type": "integer",
      "default": 30,
      "maximum": 365,
      "minimum": 1,
      "description": "Look back this many days (ignored when from is given)"
    },
    "from": {
      "type": "string",
      "format": "date",
      "description": "Start date, YYYY-MM-DD (UTC)"
    },
    "address": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{40}$",
      "description": "Public Hyperliquid wallet address"
    }
  },
  "additionalProperties": false
}

get_tax_summary

Free. Per-venue realised gains and losses, fees, funding, liquidations, open positions and items needing review for one wallet and tax year, plus trading analytics (fee and funding drag, liquidation review, net after costs by market and month). For live wallets, report gives the event count, the full report's price for this caller, whether they already have access, and how to buy it.

read-only

Argument	Type	Description
sample	boolean	Return deterministic sample data instead of reading Hyperliquid
address*	string	Public Hyperliquid wallet address
tax_year	string	Tax year. AU-2027 = Australia · FY 2026–27; AU-2026 = Australia · FY 2025–26; US-2026 = United States · 2026; US-2025 = United States · 2025; UK-2027 = United Kingdom · 2026–27; UK-2026 = United Kingdom · 2025–26; CA-2026 = Canada · 2026; CA-2025 = Canada · 2025; NZ-2027 = New Zealand · 2026–27; NZ-2026 = New Zealand · 2025–26; JP-2026 = Japan · 2026; JP-2025 = Japan · 2025; ES-2026 = Spain · 2026; ES-2025 = Spain · 2025. Defaults by jurisdiction: AU AU-2026, US US-2026, UK UK-2026, CA CA-2026, NZ NZ-2027, JP JP-2026, ES ES-2026.
jurisdiction	string	Used when tax_year is not given. AU = 1 Jul–30 Jun; US, CA, JP and ES = calendar year; UK = 6 Apr–5 Apr; NZ = 1 Apr–31 Mar
unlock_token	string	Unlock token returned by buy_report (or the website after paying), for wallets bought without an API key

get_top_traders

Free, read-only. papertrade's top traders by profit and loss over 24h, 7d, 30d or all time, or a search by leaderboard name or wallet, with the X account a trader signed in with, if any, and a link to their page on papertax.xyz/traders, where people can follow them. Not recommendations.

read-only

Argument	Type	Description
query	string	A leaderboard name (2+ letters) or a 0x wallet
window	string

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 42,
      "description": "A leaderboard name (2+ letters) or a 0x wallet"
    },
    "window": {
      "enum": [
        "24h",
        "7d",
        "30d",
        "all"
      ],
      "type": "string",
      "default": "7d"
    }
  },
  "additionalProperties": false
}

preview_papertrade_close

Free, read-only. What closing one papertrade position (or all of them) would keep at the current price or a price you give, and what that does to the wallet's realised net for a tax year (all venues, and papertrade alone). Answers "what would closing my ETH long do to my tax year?". An estimate, not tax advice; nothing is closed.

read-only

Argument	Type	Description
price	number	A price to close at (one market only); defaults to the current price
address*	string	Public Hyperliquid wallet address
tax_year	string	Tax year. AU-2027 = Australia · FY 2026–27; AU-2026 = Australia · FY 2025–26; US-2026 = United States · 2026; US-2025 = United States · 2025; UK-2027 = United Kingdom · 2026–27; UK-2026 = United Kingdom · 2025–26; CA-2026 = Canada · 2026; CA-2025 = Canada · 2025; NZ-2027 = New Zealand · 2026–27; NZ-2026 = New Zealand · 2025–26; JP-2026 = Japan · 2026; JP-2025 = Japan · 2025; ES-2026 = Spain · 2026; ES-2025 = Spain · 2025. Defaults by jurisdiction: AU AU-2026, US US-2026, UK UK-2026, CA CA-2026, NZ NZ-2027, JP JP-2026, ES ES-2026.
position_id	string	From get_papertrade_positions; leave out to close all
jurisdiction	string	Used when tax_year is not given. AU = 1 Jul–30 Jun; US, CA, JP and ES = calendar year; UK = 6 Apr–5 Apr; NZ = 1 Apr–31 Mar

Input schema (JSON)

papertax

Try it

buy_report

papertax

Try it

buy_report

Tools (11)