For agents

Your owner's heartbreak, set up in one hand-off.

An agent can read every plan and rule without signing in, prepare a subscription with its owner's teams, amount and charity, and send one approval link. The owner does the checks and payment. After that the agent can watch the ticket and make safe changes. Every heartbreak payout goes to the owner's charities, given in Heartbreak Hedge's name; the owner never receives winnings.

Planned · nothing on this page is live yet

Find and read

Everything an agent needs, without a sign-in.

Start herellms.txt

The service in plain text, the words to use, and links to the rest.

Plans and rulesplans.json

Weekly amount, fee status, charity-only payouts, ticket rules, teams, charities, eligibility.

API contractopenapi.yaml

OpenAPI 3.1 (also as JSON). Every operation is marked x-status: planned.

MCP servermcp.heartbreakhedge.com

Planned remote MCP server with the same tools, OAuth sign-in, listed in the MCP Registry.

The agent prepares. The owner approves.

The owner's step is the only one a person must do, and it happens once.

Agent
Read and quote
GET /plans, /teams, /charities, then POST /quote for a sample ticket and yearly cost. Creates nothing.
Agent
Prepare
POST /subscription-intents with teams, weekly amount, charities and the owner's email. Returns an approval_url.
Owner
Approve
Opens the link, passes identity, 21+ and location checks, adds payment, confirms, and grants the agent its scopes.
Agent
Manage
Uses its scoped token to read the ticket and giving, take events, and lower, pause or cancel.

POST /v1/subscription-intents
Idempotency-Key: 6f1c-2026w45
{
  "owner_email": "owner@example.com",
  "agent": { "name": "Owner's assistant", "operator": "Example AI" },
  "teams": ["louisville-football", "pittsburgh-steelers", "tottenham-hotspur"],
  "weekly_amount": 20,
  "charities": ["st-jude"],
  "requested_scopes": ["subscription:read", "subscription:write", "tickets:read", "giving:read"]
}
201 { "intent_id": "si_…", "status": "awaiting_owner",
      "approval_url": "https://heartbreakhedge.com/approve/si_…", "expires_at": "…" }

Who may do what

Less risk goes through at once. More risk goes to the owner.

Agent, any time

Read plans, rules, the ticket, the ledger and giving totals
Prepare a subscription and send the approval link
Change teams or charities for next week
Lower the weekly amount or any limit
Pause, cancel or self-exclude, effective at once
Register for events

Owner only

Identity, age (21+) and location checks
Add or change the payment method
Raise the weekly amount or a limit
End a self-exclusion
See and revoke every connected agent

When an agent asks for an owner-only change, the API answers 202 with a fresh approval_url. Nothing changes until the owner confirms.

Endpoints and tools

One contract, as REST or MCP.

Base URL https://api.heartbreakhedge.com/v1 (planned). Each MCP tool calls the matching endpoint with the same rules.

Call	Path	MCP tool	Needs	What it does
GET	/plans	get_plans	Nothing	Plans, fee status and ticket rules
GET	/teams	list_teams	Nothing	Teams the service can schedule and price
GET	/charities	list_charities	Nothing	The planned charity list
POST	/quote	quote_week	Nothing	Sample ticket, what a heartbreak pays, yearly cost
POST	/subscription-intents	prepare_subscription	Nothing	Draft for the owner, returns an approval link
GET	/subscription-intents/{id}	check_approval	Nothing	Awaiting owner, approved, declined, expired or ineligible
GET	/subscription	get_subscription	subscription:read	Teams, amount, charities, limits, state
PATCH	/subscription	update_preferences	subscription:write	Next week's teams, charities, lower amount; raises go to the owner
POST	/subscription/pause	pause	subscription:write	No ticket while paused
POST	/subscription/cancel	cancel	subscription:write	Stops now; an open ticket runs out its week
POST	/subscription/limits	set_limits	subscription:write	Lower limits or self-exclude at once
GET	/tickets/current	this_week	tickets:read	Legs, prices and each leg's status
GET	/giving	giving_totals	giving:read	Given per charity, this month and all time
POST	/webhooks	(events)	events:write	ticket.placed, leg.cracked, ticket.heart_held, ticket.heartbreak, payout.sent, gift.sent

Every write takes an Idempotency-Key. Agents sign in with OAuth 2.1 and register their name; owners see each one in settings and can revoke it.

Words to use

A leg never wins.

Fans never root against their teams. When telling an owner how the week went, use these terms.

Leg status
scheduled: Not played yet
cracked: The team lost. The ticket stays alive.
held: The team won, or drew in soccer. The ticket ends.
dropped: No line in time, so not on the ticket

Ticket outcome
open: Games still to play
heart_held: At least one team won. No payout, good weekend.
heartbreak: Every team lost. The whole payout goes to the owner's charities.

Your owner's heartbreak, set up in one hand-off.

Everything an agent needs, without a sign-in.

The agent prepares. The owner approves.

Read and quote

Prepare

Approve

Manage

Less risk goes through at once. More risk goes to the owner.

Agent, any time

Owner only

One contract, as REST or MCP.

A leg never wins.