# FIDE Ratings — 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.

> Find chess players and track their FIDE ratings, rankings, and performance history by searching the official ratings database or browsing the world's top-ranked players. Get detailed player profiles with complete rating trends and game statistics to analyze any player's competitive record.

**Category:** Sports | **Website:** [ratings.fide.com/](https://ratings.fide.com/) | **Docs:** [parse.bot/marketplace/6bbce1ef-d137-46c5-ba78-fda6015026e1/ratings-fide-com-api](https://parse.bot/marketplace/6bbce1ef-d137-46c5-ba78-fda6015026e1/ratings-fide-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/fide-ratings/`
**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 player profile

Retrieve complete profile information for a player by FIDE ID, including ratings across all time controls, ranking history, game statistics (wins/draws/losses by color and time control), opponents list, and top ranking records. The profile also includes the player's photo, title, federation, and birth year.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fide_id` | string | Yes | The unique FIDE ID of the player (numeric string, e.g. 1503014) |

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

### Get player titles

Retrieve a player's non-playing FIDE titles and designations (arbiter, trainer, etc.) by their FIDE ID. Returns the player's name and a list of titles/designations from the 'FIDE Arbiter/Trainer' section of their profile, including license level, license status, and title entries such as National Arbiter (NA), FIDE Arbiter (FA), International Arbiter (IA), and trainer designations. Returns an empty titles array if the player has no non-playing titles.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fide_id` | string | Yes | The unique FIDE ID of the player (numeric string, e.g. 1503545) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/fide-ratings/get-player-titles \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"fide_id":"<string>"}'
```

### Get top players

Fetch the top 100 players list for a given category. Returns rank, name, FIDE ID, federation, rating, and birth year for each player. The category determines which ranking list is returned (e.g. open, women, juniors). Results are ordered by rank descending.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Ranking category. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/fide-ratings/get-top-players \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>"}'
```

### Search players

Search for players in the FIDE database by name or FIDE ID. Returns all matching players with their title, federation, ratings across all time controls (standard, rapid, blitz), and birth year. Partial name matches are supported.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query (player name or FIDE ID) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/fide-ratings/search-players \
  -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.