{"openapi":"3.1.0","info":{"title":"Subnet Metrics — dTAO tax pack API","version":"1.0.0","summary":"Read-only: the free exposure check, an order's status, and the fulfilled pack.","description":"Three GET endpoints, no authentication beyond the per-order token that the buyer receives in the Stripe success URL and the delivery email. A computation tool applying the method at /tax/method — not tax advice. Never quote or infer Taostats' pricing from this site.","contact":{"name":"Subnet Metrics","email":"hello@subnetmetrics.com","url":"https://subnetmetrics.com/tax"},"termsOfService":"https://subnetmetrics.com/tax/terms"},"servers":[{"url":"https://subnetmetrics.com"}],"paths":{"/tax/check.json":{"get":{"operationId":"exposureCheck","summary":"Free exposure check for one coldkey","description":"One chain read (cached 24 h per coldkey). Returns the coldkey's staked TAO, alpha valued as TAO at pool price, and an estimate of this UK tax year's emissions income and the tax on it at 40% and 45%, using the network's chain-derived yield. An estimate, not the computation; the pack does the computation. Nothing is stored about the caller.","parameters":[{"name":"coldkey","in":"query","required":true,"description":"A Bittensor coldkey (SS58 public address, never a seed).","schema":{"type":"string","pattern":"^5[1-9A-HJ-NP-Za-km-z]{46,48}$"},"example":"5FAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAb"}],"responses":{"200":{"description":"The check. `state` is ok, notfound, unconfigured, ratelimited or error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Exposure"},"example":{"state":"ok","coldkey":"5FAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAb","staked_tao":729.6,"root_tao":118.4,"alpha_as_tao":611.2,"free_tao":0.0,"events":242,"tax_year":"2026/27","yield":0.169,"yield_root":0.074,"yield_alpha":0.187,"yield_source":"chain","alpha_yield_source":"pool","tao_gbp":171.2,"tao_usd":228.3,"income_tao":123.4,"income_gbp":21126.0,"tax40":8450.0,"tax45":9507.0,"staked_gbp":124907.0}}}},"400":{"description":"Malformed input (a coldkey that is not 47–48 base58 characters starting with 5).","content":{"application/json":{"example":{"state":"badkey"}}}},"429":{"description":"Rate limit: 20 requests per hour per IP across the check and order endpoints.","content":{"application/json":{"example":{"error":"rate limited","retry_after_s":3600}}}}}}},"/tax/orders/{order_id}":{"get":{"operationId":"orderStatus","summary":"Status of a pack order","description":"created → paid → fulfilled. `pack_url` appears once fulfilled and is valid for 30 days after fulfilment (`pack_expires_at`).","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"},"example":"k3Qm9xP2vT1a"},{"name":"t","in":"query","required":true,"description":"The order token: HMAC-SHA256 of the order id, hex. Sent in the Stripe success URL (`ot`) and the delivery email.","schema":{"type":"string","pattern":"^[0-9a-f]{64}$"},"example":"3f6a…(64 hex chars)"}],"responses":{"200":{"description":"The order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"example":{"id":"k3Qm9xP2vT1a","status":"fulfilled","pack":{"sku":"uk_launch","name":"UK return pack — launch price","kind":"uk"},"coldkeys":["5FAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAb"],"created_at":"2026-09-04T10:12:03Z","paid_at":"2026-09-04T10:14:41Z","fulfilled_at":"2026-09-21T08:02:10Z","pack_url":"https://subnetmetrics.com/tax/orders/k3Qm9xP2vT1a/pack?t=3f6a…(64 hex chars)","pack_expires_at":"2026-10-21T08:02:10Z","retention_days":30}}}},"404":{"description":"Unknown order, or a wrong or missing token — the same answer for both.","content":{"application/json":{"example":{"error":"not found"}}}},"429":{"description":"Rate limit: 20 requests per hour per IP across the check and order endpoints.","content":{"application/json":{"example":{"error":"rate limited","retry_after_s":3600}}}}}}},"/tax/orders/{order_id}/pack":{"get":{"operationId":"orderPack","summary":"Download the fulfilled pack (zip)","description":"The zip the delivery email carried: the PDF and every CSV. Only while `status` is fulfilled and for 30 days after.","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string"},"example":"k3Qm9xP2vT1a"},{"name":"t","in":"query","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"},"example":"3f6a…(64 hex chars)"}],"responses":{"200":{"description":"The pack.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Unknown order, or a wrong or missing token — the same answer for both.","content":{"application/json":{"example":{"error":"not found"}}}},"409":{"description":"The order exists but has no pack yet (not paid, or paid and not yet fulfilled).","content":{"application/json":{"example":{"error":"not fulfilled","status":"paid"}}}},"410":{"description":"The pack existed but was purged: packs are kept 30 days after fulfilment.","content":{"application/json":{"example":{"error":"expired","retention_days":30}}}},"429":{"description":"Rate limit: 20 requests per hour per IP across the check and order endpoints.","content":{"application/json":{"example":{"error":"rate limited","retry_after_s":3600}}}}}}}},"components":{"schemas":{"Exposure":{"type":"object","required":["state","coldkey"],"properties":{"state":{"type":"string","enum":["ok","notfound","unconfigured","ratelimited","error"]},"coldkey":{"type":"string"},"staked_tao":{"type":"number"},"root_tao":{"type":"number"},"alpha_as_tao":{"type":"number"},"free_tao":{"type":"number"},"events":{"type":["integer","null"],"description":"stake events on chain"},"tax_year":{"type":"string","description":"UK tax year, e.g. 2026/27"},"yield":{"type":"number","description":"blended annual yield used, as a fraction"},"yield_root":{"type":"number"},"yield_alpha":{"type":"number"},"yield_source":{"type":"string"},"alpha_yield_source":{"type":["string","null"]},"tao_gbp":{"type":["number","null"]},"tao_usd":{"type":["number","null"]},"income_tao":{"type":"number"},"income_gbp":{"type":"number"},"tax40":{"type":"number","description":"at the higher rate"},"tax45":{"type":"number","description":"at the additional rate"},"staked_gbp":{"type":"number"},"cached":{"type":"boolean"},"fetched_at":{"type":"integer","description":"unix seconds"}}},"Order":{"type":"object","required":["id","status","pack","coldkeys","created_at"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["created","paid","fulfilled"]},"pack":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["uk","us","accountant"]}}},"coldkeys":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"fulfilled_at":{"type":["string","null"],"format":"date-time"},"pack_url":{"type":["string","null"]},"pack_expires_at":{"type":["string","null"],"format":"date-time"},"retention_days":{"type":"integer"}}}}}}