# Racing Hkjc — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access comprehensive horse racing data from the Hong Kong Jockey Club. Retrieve race results, detailed horse profiles including pedigree and form records, jockey and trainer season rankings, upcoming race meeting fixtures, and horse search by name.

**Category:** Sports | **Website:** [racing.hkjc.com/](https://racing.hkjc.com/) | **Docs:** [parse.bot/marketplace/c63a11c0-d95f-4ec9-9cbf-04413acbd57d/racing-hkjc-com-api](https://parse.bot/marketplace/c63a11c0-d95f-4ec9-9cbf-04413acbd57d/racing-hkjc-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/racing-hkjc/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get horse profile

Retrieve comprehensive horse profile by horse ID. Returns pedigree, trainer, owner, rating, and stakes data. Field availability varies by horse — retired horses may have fewer fields.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `horse_id` | string | Yes | Horse ID in format like HK_2020_E436. Obtainable from search_horses results or race result finishers. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/racing-hkjc/get-horse-profile \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"horse_id":"<string>"}'
```

### Get jockey ranking

Retrieve the current season jockey rankings/standings. Returns all active jockeys sorted by wins with their stakes won. No input required — always returns the current season data.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/racing-hkjc/get-jockey-ranking \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get race meeting fixtures

Retrieve the schedule of upcoming race meetings for the current month. Returns local and overseas race day events with dates as Unix millisecond timestamps. Automatically uses the current season and month.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/racing-hkjc/get-race-meeting-fixtures \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get race results

Retrieve full race results for a specific race meeting date and race number. Returns finishers with placings, times, odds, and dividends. Metadata fields (venue, class, distance, going, course) are extracted when available from the page structure.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date` | string | Yes | Race date in YYYYMMDD format (e.g., 20250608). |
| `race_no` | integer | No | Race number within the meeting (1-11 typical). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/racing-hkjc/get-race-results \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"date":"<string>","race_no":"<integer>"}'
```

### Get trainer ranking

Retrieve the current season trainer rankings/standings. Returns all trainers sorted by wins with their stakes won. No input required — always returns the current season data.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/racing-hkjc/get-trainer-ranking \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Search horses

Search for horses by name. Supports partial name matching and returns both current and retired horses. Returns horse IDs usable with get_horse_profile.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Horse name to search for (e.g., 'GOLDEN', 'LUCKY'). Supports partial matching. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/racing-hkjc/search-horses \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.