{ "openapi": "3.1.0", "info": { "title": "PaperTax API", "version": "0.7.0", "description": "Read-only tax records for Hyperliquid perps and HIP-3 markets. Default classifications for review, not tax advice. Rate limited per IP.", "contact": { "name": "PaperTax", "url": "https://x.com/papertaxdev", "email": "nick@astrnt.me" } }, "servers": [ { "url": "https://papertax.xyz" } ], "paths": { "/api/ledger": { "post": { "operationId": "getLedger", "summary": "Full ledger for a wallet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "example": "0xb317D2BC2D3d2Df5Fa441B5bAE0AB9d8b07283ae" }, "year": { "type": "string", "enum": [ "AU-2027", "AU-2026", "US-2026", "US-2025", "UK-2027", "UK-2026", "CA-2026", "CA-2025", "NZ-2027", "NZ-2026" ], "description": "Tax year to read" } } } } } }, "responses": { "200": { "description": "Ledger", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" }, "sample": { "type": "boolean" }, "present": { "type": "array", "items": { "type": "string" }, "description": "Venue keys with activity, e.g. hl, hip3:xyz" }, "venues": { "type": "object", "additionalProperties": { "type": "object" } }, "events": { "type": "array", "items": { "type": "object", "properties": { "t": { "type": "integer" }, "v": { "type": "string" }, "type": { "type": "string", "enum": [ "open", "loss", "liq", "gain", "queued", "funding", "mint", "stake", "stakepay" ] }, "label": { "type": "string" }, "market": { "type": "string" }, "side": { "type": "string", "enum": [ "long", "short" ] }, "pnl": { "type": "number" }, "fee": { "type": "number" }, "tx": { "type": "string" } } } }, "open": { "type": "array", "items": { "type": "object" } }, "coverage": { "type": "object", "properties": { "hyperliquid": { "type": "object", "properties": { "fills": { "type": "integer" }, "fundingRows": { "type": "integer" }, "truncated": { "type": "boolean" }, "readUntil": { "type": "integer" } } }, "pools": { "type": "object" } } } } } } } }, "400": { "description": "Bad address", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Rate limited" }, "502": { "description": "Hyperliquid unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/export": { "get": { "operationId": "exportTaxFile", "summary": "Export file for a wallet and tax year", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "example": "0xb317D2BC2D3d2Df5Fa441B5bAE0AB9d8b07283ae" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "koinly", "ctc", "summary", "audit", "auditpdf" ] } }, { "name": "sample", "in": "query", "schema": { "type": "string", "enum": [ "1" ] }, "description": "Return sample data" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "AU-2027", "AU-2026", "US-2026", "US-2025", "UK-2027", "UK-2026", "CA-2026", "CA-2025", "NZ-2027", "NZ-2026" ] }, "description": "Tax year. AU-2026 = Australian FY 2025-26." }, { "name": "venues", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated venue keys to include, e.g. hl,hip3:xyz" }, { "name": "unlock", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Unlock token from a purchase (alternative to the x-papertax-unlock header)." } ], "responses": { "200": { "description": "CSV or text file", "headers": { "x-papertax-truncated": { "schema": { "type": "string" } } }, "content": { "text/csv": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Bad input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Live wallet without a paid report or plan. Body has error, access and unlockUrl." }, "429": { "description": "Rate limited" }, "502": { "description": "Hyperliquid unavailable" } } } }, "/mcp": { "post": { "operationId": "mcp", "summary": "MCP server (Streamable HTTP, JSON-RPC 2.0)", "description": "Tools: get_tax_summary, get_ledger_events, export_tax_file, explain_tax_treatment, create_verified_pnl (buy_report with ?tools=all).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "JSON-RPC response" }, "202": { "description": "Notification accepted" } } } }, "/api/buy": { "post": { "operationId": "buyReport", "summary": "Buy a tax report without checkout (agents)", "description": "Card (API key + owner opt-in) or USDC on HyperEVM (quote, then claim with tx hash). Returns an unlock token and export links.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "tax_year": { "type": "string", "enum": [ "AU-2027", "AU-2026", "US-2026", "US-2025", "UK-2027", "UK-2026", "CA-2026", "CA-2025", "NZ-2027", "NZ-2026" ] }, "method": { "type": "string", "enum": [ "card", "usdc" ] }, "max_price_cents": { "type": "integer" }, "quote_id": { "type": "string" }, "tx_hash": { "type": "string" } } } } } }, "responses": { "200": { "description": "Quote, or paid with unlockToken and downloads" }, "402": { "description": "Payment declined, over a limit, or transfer not found" }, "403": { "description": "Agent purchases switched off by the owner" } } }, "get": { "operationId": "buyReportX402", "summary": "Buy a tax report with x402 (USDC on Base or Solana)", "description": "Without a payment header: 402 with x402 payment requirements (PAYMENT-REQUIRED header for x402 v2; x402Version 1 accepts in the body). Retry with PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1) to pay; returns the unlock token and export links.", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "year", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "AU-2027", "AU-2026", "US-2026", "US-2025", "UK-2027", "UK-2026", "CA-2026", "CA-2025", "NZ-2027", "NZ-2026" ] } }, { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment payload (base64 JSON)" }, { "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v1 payment payload (base64 JSON)" } ], "responses": { "200": { "description": "Paid: unlock token and export links" }, "402": { "description": "Payment required (x402)" }, "409": { "description": "No activity for this wallet and year" } } } }, "/api/verified": { "post": { "operationId": "createVerifiedPnl", "summary": "Create a signed, public verified-PnL link with a share image", "description": "Free. Reads the wallet from the chain and returns a /v/ URL whose figures are signed. Dollar amounts only when amounts is true. Proves what the wallet did, not who owns it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "year": { "type": "string", "example": "AU-2026" }, "jurisdiction": { "type": "string", "enum": [ "AU", "US", "UK", "CA", "NZ" ] }, "amounts": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "Link created", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "image": { "type": "string" }, "headline": { "type": "string" }, "period": { "type": "string" }, "summary": { "type": "string" }, "claim": { "type": "object" } } } } } }, "404": { "description": "No activity in that year" } } } }, "/api/partner": { "get": { "operationId": "partnerEarnings", "summary": "Partner info (?ref=) or the caller's partner earnings", "description": "With ?ref=: public name and site. Without: earnings for the signed-in partner (Authorization: Bearer ), net of refunds and Stripe fees, by month, with paid and owed.", "parameters": [ { "name": "ref", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Partner info or earnings" }, "401": { "description": "Missing or bad key" }, "404": { "description": "Unknown ref" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "PaperTax API key (ptx_…) from /account, or a signed-in session token." } } }, "security": [ {}, { "apiKey": [] } ] }