{
    "openapi": "3.1.0",
    "info": {
        "title": "Lottery After Taxes API",
        "version": "1.0.0",
        "summary": "What a Powerball or Mega Millions jackpot is worth after federal, state and local taxes in any US state.",
        "description": "Free, read-only JSON. No key. 60 requests a minute per IP address on /api/v1/net. Figures use 2026 federal tax rules, each state's rules for lottery prizes and the official current jackpots; they are estimates, not tax advice. Show them with a link to Lottery After Taxes (lotteryaftertaxes.com). Method: https://lotteryaftertaxes.com/methodology/",
        "contact": {
            "name": "Pablo Bravo Villanueva",
            "email": "pablobravo44@gmail.com",
            "url": "https://lotteryaftertaxes.com/contact/"
        },
        "license": {
            "name": "Free with attribution",
            "url": "https://lotteryaftertaxes.com/terms/"
        }
    },
    "servers": [
        {
            "url": "https://lotteryaftertaxes.com"
        }
    ],
    "externalDocs": {
        "description": "API documentation",
        "url": "https://lotteryaftertaxes.com/api/"
    },
    "tags": [
        {
            "name": "taxes",
            "description": "After-tax value of a jackpot or prize"
        },
        {
            "name": "jackpots",
            "description": "Current jackpots"
        }
    ],
    "paths": {
        "/api/v1/net": {
            "get": {
                "operationId": "getNet",
                "tags": [
                    "taxes"
                ],
                "summary": "After-tax value of a jackpot for a winner in one state",
                "description": "Cash option (federal tax withheld at claim, federal tax due at filing, state and local tax, net) and the 30-payment annuity. Without amount, the current jackpot and its official cash value are used.",
                "parameters": [
                    {
                        "name": "state",
                        "in": "query",
                        "required": true,
                        "description": "Two-letter postal code of the state the winner lives in (DC for the District of Columbia). Case-insensitive.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "AL",
                                "AK",
                                "AZ",
                                "AR",
                                "CA",
                                "CO",
                                "CT",
                                "DE",
                                "DC",
                                "FL",
                                "GA",
                                "HI",
                                "ID",
                                "IL",
                                "IN",
                                "IA",
                                "KS",
                                "KY",
                                "LA",
                                "ME",
                                "MD",
                                "MA",
                                "MI",
                                "MN",
                                "MS",
                                "MO",
                                "MT",
                                "NE",
                                "NV",
                                "NH",
                                "NJ",
                                "NM",
                                "NY",
                                "NC",
                                "ND",
                                "OH",
                                "OK",
                                "OR",
                                "PA",
                                "RI",
                                "SC",
                                "SD",
                                "TN",
                                "TX",
                                "UT",
                                "VT",
                                "VA",
                                "WA",
                                "WV",
                                "WI",
                                "WY"
                            ]
                        },
                        "example": "TX"
                    },
                    {
                        "name": "game",
                        "in": "query",
                        "required": false,
                        "description": "Game (mega_millions is accepted too).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "powerball",
                                "mega-millions"
                            ],
                            "default": "powerball"
                        }
                    },
                    {
                        "name": "amount",
                        "in": "query",
                        "required": false,
                        "description": "Advertised jackpot in whole dollars. Omit it for the current jackpot.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 10000000000
                        },
                        "example": 500000000
                    },
                    {
                        "name": "cash",
                        "in": "query",
                        "required": false,
                        "description": "Cash value in whole dollars, not more than amount. Without it, the current jackpot uses its official cash value and any other amount the latest official cash-to-jackpot ratio.",
                        "schema": {
                            "type": "integer",
                            "minimum": 0
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Federal filing status. Aliases: married and joint (married_joint), separate (married_separate), hoh (head_of_household).",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "single",
                                "married_joint",
                                "married_separate",
                                "head_of_household",
                                "married",
                                "joint",
                                "separate",
                                "hoh"
                            ],
                            "default": "single"
                        }
                    },
                    {
                        "name": "local",
                        "in": "query",
                        "required": false,
                        "description": "City income tax on top of the state tax. Only with state=NY.",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "nyc",
                                "yonkers"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The after-tax breakdown",
                        "headers": {
                            "X-RateLimit-Limit": {
                                "description": "Requests allowed per minute",
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "X-RateLimit-Remaining": {
                                "description": "Requests left in the current minute",
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Net"
                                },
                                "example": {
                                    "game": "powerball",
                                    "tax_year": 2026,
                                    "state": "TX",
                                    "local": null,
                                    "status": "single",
                                    "state_rule_verified": true,
                                    "advertised": 500000000,
                                    "cash": 213350000,
                                    "cash_is_estimate": true,
                                    "lump_sum": {
                                        "federal_withheld": 51204000,
                                        "federal_due_at_filing": 27685500.25,
                                        "federal_total": 78889500.25,
                                        "state": 0,
                                        "local": 0,
                                        "net": 134460499.75
                                    },
                                    "annuity": {
                                        "payments": 30,
                                        "annual_increase": 0.05,
                                        "first_payment_gross": 7525717.54,
                                        "first_payment_net": 4791201.8,
                                        "total_net": 316499992.5
                                    },
                                    "break_even_after_tax_return": 0.05455,
                                    "methodology": "https://lotteryaftertaxes.com/methodology/",
                                    "attribution": "Lottery After Taxes https://lotteryaftertaxes.com/"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid input",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded",
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds until the limit resets",
                                "schema": {
                                    "type": "integer"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/jackpots": {
            "get": {
                "operationId": "getJackpots",
                "tags": [
                    "jackpots"
                ],
                "summary": "Current jackpots, cash values and next drawings",
                "responses": {
                    "200": {
                        "description": "Both games",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Jackpots"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Net": {
                "type": "object",
                "required": [
                    "game",
                    "tax_year",
                    "state",
                    "local",
                    "status",
                    "state_rule_verified",
                    "advertised",
                    "cash",
                    "cash_is_estimate",
                    "lump_sum",
                    "annuity",
                    "break_even_after_tax_return",
                    "methodology",
                    "attribution"
                ],
                "properties": {
                    "game": {
                        "type": "string",
                        "enum": [
                            "powerball",
                            "mega-millions"
                        ]
                    },
                    "tax_year": {
                        "type": "integer",
                        "description": "Tax year of the federal and state rules"
                    },
                    "state": {
                        "type": "string",
                        "description": "Two-letter code of the state the winner lives in"
                    },
                    "local": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "enum": [
                            "nyc",
                            "yonkers",
                            null
                        ]
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "single",
                            "married_joint",
                            "married_separate",
                            "head_of_household"
                        ]
                    },
                    "state_rule_verified": {
                        "type": "boolean",
                        "description": "false when the state's treatment of lottery prizes is not yet confirmed against an official source"
                    },
                    "advertised": {
                        "type": "number",
                        "description": "Advertised jackpot (the sum of the 30 annuity payments). In US dollars."
                    },
                    "cash": {
                        "type": "number",
                        "description": "Cash option before tax. In US dollars."
                    },
                    "cash_is_estimate": {
                        "type": "boolean",
                        "description": "true when the cash value is estimated from the latest official cash-to-jackpot ratio"
                    },
                    "lump_sum": {
                        "type": "object",
                        "required": [
                            "federal_withheld",
                            "federal_due_at_filing",
                            "federal_total",
                            "state",
                            "local",
                            "net"
                        ],
                        "properties": {
                            "federal_withheld": {
                                "type": "number",
                                "description": "Federal tax withheld when the prize is claimed. In US dollars."
                            },
                            "federal_due_at_filing": {
                                "type": "number",
                                "description": "Federal tax still owed when filing; negative means a refund. In US dollars."
                            },
                            "federal_total": {
                                "type": "number",
                                "description": "Total federal tax. In US dollars."
                            },
                            "state": {
                                "type": "number",
                                "description": "State tax. In US dollars."
                            },
                            "local": {
                                "type": "number",
                                "description": "City tax (New York City or Yonkers). In US dollars."
                            },
                            "net": {
                                "type": "number",
                                "description": "What the winner keeps from the cash option. In US dollars."
                            }
                        }
                    },
                    "annuity": {
                        "type": "object",
                        "required": [
                            "payments",
                            "annual_increase",
                            "first_payment_gross",
                            "first_payment_net",
                            "total_net"
                        ],
                        "properties": {
                            "payments": {
                                "type": "integer",
                                "description": "Number of yearly payments"
                            },
                            "annual_increase": {
                                "type": "number",
                                "description": "Yearly increase of each payment (0.05 = 5%)"
                            },
                            "first_payment_gross": {
                                "type": "number",
                                "description": "First payment before tax. In US dollars."
                            },
                            "first_payment_net": {
                                "type": "number",
                                "description": "First payment after tax. In US dollars."
                            },
                            "total_net": {
                                "type": "number",
                                "description": "All payments after tax, added up. In US dollars."
                            }
                        }
                    },
                    "break_even_after_tax_return": {
                        "type": [
                            "number",
                            "null"
                        ],
                        "description": "Yearly after-tax return at which the cash option funds the same after-tax payments as the annuity (0.055 = 5.5%); null when it cannot be solved"
                    },
                    "methodology": {
                        "type": "string",
                        "format": "uri"
                    },
                    "attribution": {
                        "type": "string"
                    }
                }
            },
            "Jackpot": {
                "type": "object",
                "required": [
                    "advertised",
                    "cash",
                    "next_drawing",
                    "updated_at",
                    "stale"
                ],
                "properties": {
                    "advertised": {
                        "type": "number",
                        "description": "Advertised jackpot for the next drawing. In US dollars."
                    },
                    "cash": {
                        "type": "number",
                        "description": "Official cash value. In US dollars."
                    },
                    "next_drawing": {
                        "type": "string",
                        "format": "date"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When the values were last confirmed"
                    },
                    "stale": {
                        "type": "boolean",
                        "description": "true when the jackpot was not refreshed after the last drawing"
                    }
                }
            },
            "Jackpots": {
                "type": "object",
                "required": [
                    "jackpots"
                ],
                "properties": {
                    "jackpots": {
                        "type": "object",
                        "required": [
                            "powerball",
                            "mega-millions"
                        ],
                        "properties": {
                            "powerball": {
                                "$ref": "#/components/schemas/Jackpot"
                            },
                            "mega-millions": {
                                "$ref": "#/components/schemas/Jackpot"
                            }
                        }
                    }
                }
            },
            "Error": {
                "type": "object",
                "required": [
                    "error"
                ],
                "properties": {
                    "error": {
                        "type": "string",
                        "description": "What is wrong with the request"
                    },
                    "docs": {
                        "type": "string",
                        "format": "uri"
                    }
                }
            }
        }
    }
}