For agents

How an AI agent, or the developer building one, gets HalfPoint's data: fixtures, live scores, venue mappings, grades and a market-implied consensus probability for MLB, NBA, NFL, college football, NHL, the Premier League, the Bundesliga, LaLiga and the Champions League. Every page of these docs is also Markdown: add .md to its path (this one: /agents.md); llms.txt lists them all.

1. Try it without a key

The sample answers without a key: one league, delayed, 10 fixtures.

curl "https://odds.halfpoint.tech/sample/odds?league=nba"
curl "https://fixtures.halfpoint.tech/sample/fixtures?league=nba"

2. Describe the API to your agent

Both hosts serve an OpenAPI 3.0 description of every route, its parameters and errors, without a key:

https://odds.halfpoint.tech/openapi.json
https://fixtures.halfpoint.tech/openapi.json

3. Get a key

A key works on both hosts and gets what its plan includes: Consensus USD 49 a month, Realtime 249, Risk 799 (or 490, 2,490 and 7,990 a year). Subscribe with a card in a browser at

https://account.halfpoint.tech/checkout?plan=consensus      # or realtime, risk; &interval=year

The page names the plan, its price and its trial and asks for your email; its button takes you to Stripe. Consensus and Realtime start with a 7-day free trial (card required; one trial per customer and email); Risk has none. The key is shown once after the checkout; it can be rotated after logging in with your email at https://account.halfpoint.tech/login. See After you pay.

Send it as the X-Api-Key header:

curl -H "X-Api-Key: $HALFPOINT_KEY" "https://odds.halfpoint.tech/odds?league=nba"

4. Or connect over MCP

An MCP server (streamable HTTP) offers the same data as tools:

https://mcp.halfpoint.tech/

tool	does	key
get_sample	the sample above: kind odds or fixtures, one league	no
get_pass_options	the plans, prices and checkout links	no
list_leagues	the leagues served	yes
list_fixtures	a league's schedule on a date	yes
get_live	score, period and clock of the games being played	yes
get_consensus	the consensus, of a league or one fixture	yes
get_bet_stop_status	the bet stop and widened per market	yes, plan risk

Set the key as a header in the client's config, e.g.:

{
  "mcpServers": {
    "halfpoint": {
      "type": "http",
      "url": "https://mcp.halfpoint.tech/",
      "headers": {"X-Api-Key": "hp_..."}
    }
  }
}

Authorization: Bearer hp_... works too. A client that can't set headers (some hosted connectors) can put the key in the URL instead, https://mcp.halfpoint.tech/?key=hp_...; prefer the header where you can. Without a key only get_sample and get_pass_options answer; the others say how to get one.

5. Or pay with x402

Agents with a wallet can pay in USDC with x402, without an account. Payments settle on Base (eip155:8453) in USDC.

x402 version 2 only: the payment goes in the PAYMENT-SIGNATURE header (a v1 client's X-PAYMENT is not read, and gets 402 again). Paying for a request accepts the terms.

Per request. A request without a key to /odds, /fixtures, /live or /grades answers 402 with the payment requirements in the PAYMENT-REQUIRED header (scheme exact, USDC, the amount in its smallest unit, the address paid). Retry with PAYMENT-SIGNATURE: the answer comes once the payment is settled, with PAYMENT-RESPONSE (the transaction). An x402 client library does this for you. On /odds, ?plan=x402.risk adds stop, widened and range. Only an answer that delivers data (2xx) is settled: an error is not charged, and a paid request always gets the full answer, never 304.

route	price (USD)
/odds	0.01, or 0.03 with ?plan=x402.risk
/fixtures, /live, /grades	0.002

A pass. For many calls or the stream, buy a plan for a period: it comes with a key, shown once, that works until the period ends. A pass bought without a key has no email login: a lost key is replaced by signing a message with the paying wallet (POST /x402/key, see After you pay).

POST https://account.halfpoint.tech/x402/pass?plan=realtime&period=24h

pass	price (USD)
realtime, 24h	15
risk, 24h	49
realtime, 7d	69

A payer whose settlements fail repeatedly is refused for a while (403); a payer may have 2 paid requests open at once (429 beyond), and one payment serves one request (409 while it is in use by another). While payments are starting up they answer 503 with Retry-After: 30. A pass settled but not recorded answers 500 with its transaction (tx): contact us with it.

Errors your agent should handle

status	meaning	what to do
400	invalid parameters	fix the request; the body says what
401	unknown key	check the key
402	no key, or the key's subscription has lapsed	get a key, renew, or pay with x402: the body names the options
403	the plan doesn't include this route, or the x402 payer is blocked	a higher plan
409	this x402 payment is in use by another request	wait for that request, or sign a new payment
429	too many requests, or too many streams open for the key	wait Retry-After seconds; for streams (no Retry-After), close one
451	not available in your country
503	x402 payments not available yet	retry after Retry-After seconds

Errors answer {"error": "..."}. See Errors and Polling: answers carry an ETag, and polling faster than the data changes returns the same answer.