Live Tennis API tools for the Vercel AI SDK

Install livetennisapi-ai

The package is livetennisapi-ai on npm. ai v7 is a peer dependency, so the tools use the copy your app already has. ai v7 needs Node 22 or later.

npm install livetennisapi-ai ai
pnpm add livetennisapi-ai ai
yarn add livetennisapi-ai ai
bun add livetennisapi-ai ai

Set the API key

The tools read your key from the LIVETENNISAPI_KEY environment variable. Get a free key. No card is needed.

export LIVETENNISAPI_KEY=twjp_...

You can also pass the key in code as livetennisTools({ apiKey }). The apiKey option wins over the environment variable. Each call returns a tool set bound to one key, so one process can serve users on different plans.

How do I use the tools with generateText?

Pass the whole set as tools. This example goes through the AI Gateway, which reads AI_GATEWAY_API_KEY. Any other AI SDK model that supports tool calling works in its place.

import { generateText, gateway, isStepCount } from 'ai';
import { livetennisTools } from 'livetennisapi-ai';

const { text } = await generateText({
  model: gateway('openai/gpt-5-mini'),
  prompt: 'Which tennis matches are live right now, and what are the scores?',
  tools: livetennisTools(), // reads LIVETENNISAPI_KEY
  stopWhen: isStepCount(3),
});

console.log(text);

isStepCount(3) gives the model room to call a tool and then answer.

Send only the tools you need

Each tool is also exported on its own. Every tool's description and input schema go to the model on every request, so a smaller set costs fewer tokens.

import { getLiveMatches, getMatchScore } from 'livetennisapi-ai';

const apiKey = process.env.LIVETENNISAPI_KEY;

const tools = {
  get_live_matches: getLiveMatches({ apiKey }),
  get_match_score: getMatchScore({ apiKey }),
};

Which tools are there, and which plan does each need?

Tool names, exports and plans are the ones the package defines. A tool above your key's plan still answers. It explains which plan the data needs instead of returning it.

The tools call the REST endpoints documented on the live scores, players and tournaments, results archive, odds and shot-level charting pages.

check_api_status answers even without a key. It probes a few endpoints and reports the plan it detects for the key. That is the quickest way to find out why another tool declined. Treat the plan as an estimate. A FREE key with History access reads as BASIC. Plans and prices are on the pricing page.

What happens when a tool can't return data?

A successful call returns ok: true, a readable message and the data. An empty answer is still a success, for example ok: true with no live matches. A missing or rejected key, a plan limit, a rate limit, an unknown id or a failed request returns ok: false. The message says what to do next.

{
  ok: false,
  message: 'This data requires the ULTRA plan, and the configured API key is on a lower tier. ...'
}

No tool throws for these. The model reads the message and can pass the upgrade path or the wait time on to the user.

Can I use the same tools over MCP?

The same 24 tools also run as an MCP server. The hosted endpoint is https://mcp.livetennisapi.com/mcp. Send your key as Authorization: Bearer twjp_.... To run it yourself, use npx livetennisapi-mcp. The package is livetennisapi-mcp on npm.

Links

• livetennisapi-ai on npm
• Free API key
• Authentication, quota and status