# Map World Cup 2026 IDs across providers with Machina's resolve API

Machina's resolve API takes one World Cup 2026 id, either a provider's id or a canonical Machina URN, and returns the entity with its canonical URN and its id at each provider that has one: API-Football, Sportradar, Opta, Entain and ESPN. Each call costs $0.01. Send `POST https://agents.machina.gg/zcj/fwhuudc4di78/world-cup/v1/resolve` with `{"id": "<id>"}` and pay the 402 price quote it answers with; [the buyer skill](https://agents.machina.gg/zcj/fwhuudc4di78/SKILL.md) has the steps.

## At a glance

- **Endpoint:** `POST https://agents.machina.gg/zcj/fwhuudc4di78/world-cup/v1/resolve`
- **Body:** `{"id": "<provider id or canonical URN>"}`, one id per request, matched exactly
- **Price:** $0.01
- **Payment:** a 402 price quote, paid over x402 or MPP and retried. No account or API key.
- **Response:** `data.entity` with `id` (the canonical URN), `name`, `@type`, `provider_ids` and `identity_mapping_status`
- **Coverage:** the completed FIFA World Cup 2026 archive (`archive.live` is `false`)
- **Unserved answers:** an unknown id returns `404` with `entity_not_found` and is not billed
- **Full purchase flow:** [the buyer skill](https://agents.machina.gg/zcj/fwhuudc4di78/SKILL.md)

## Resolve an ID to every provider's ID

1. Send an API-Football fixture id:

   ```bash
   curl -s -X POST https://agents.machina.gg/zcj/fwhuudc4di78/world-cup/v1/resolve \
     -H 'Content-Type: application/json' \
     -d '{"id": "1489371"}'
   ```

   This example paid $0.01. The response names the match, gives its canonical event URN and lists four provider ids. Its `@type` starts with `sport:Event`:

   ```json
   {
     "status": "success",
     "meta": {"code": 200},
     "data": {
       "count": 1,
       "entity": {
         "id": "urn:machina:sport:soccer:event:brazil-vs-morocco:20260613:wor",
         "name": "Brazil vs Morocco - FIFA World Cup 2026",
         "identity_mapping_status": "canonical",
         "provider_ids": {
           "api_football": "1489371",
           "entain": "7722038",
           "opta": "ar8b186wqraa80u0vpi2e4nis",
           "sportradar": "sr:sport_event:66456928"
         }
       },
       "archive": {"mode": "final_archive", "live": false, "status": "hit"}
     }
   }
   ```

2. Send the Sportradar id for the same match:

   ```bash
   curl -s -X POST https://agents.machina.gg/zcj/fwhuudc4di78/world-cup/v1/resolve \
     -H 'Content-Type: application/json' \
     -d '{"id": "sr:sport_event:66456928"}'
   ```

   The response returns the same canonical URN and the same four `provider_ids`, so a Sportradar id maps to the Opta, Entain and API-Football ids in one call. This example paid $0.01.

3. Send a canonical team URN:

   ```bash
   curl -s -X POST https://agents.machina.gg/zcj/fwhuudc4di78/world-cup/v1/resolve \
     -H 'Content-Type: application/json' \
     -d '{"id": "urn:machina:sport:soccer:team:brazil:bra"}'
   ```

   A team entity carries its own provider ids, which include ESPN's. This example paid $0.01. Its `@type` starts with `sport:IdentityCrosswalk`:

   ```json
   {
     "status": "success",
     "meta": {"code": 200},
     "data": {
       "count": 1,
       "entity": {
         "id": "urn:machina:sport:soccer:team:brazil:bra",
         "name": "Brazil",
         "country": "Brazil",
         "identity_mapping_status": "canonical",
         "mapping_status": {"notes": [], "verified_ids_only": true},
         "provider_ids": {"api_football": "6", "espn": "205"}
       },
       "archive": {"mode": "final_archive", "live": false, "status": "hit"}
     }
   }
   ```

4. Store the canonical URN next to your own records. It joins every provider's record for that match or team, and each `hit` serves an immutable archived row.

## Read the entity

| Field | What it holds |
| --- | --- |
| `entity.id` (also `@id`, `_id`) | The canonical Machina URN |
| `entity.name` | The match label or team name |
| `entity.@type` | The entity type, such as `sport:Event` |
| `entity.provider_ids` | One key per provider that has an id: `api_football`, `sportradar`, `opta`, `entain`, `espn` |
| `entity.identity_mapping_status` | One of `canonical`, `official_reconciled`, `provider_only`, `quarantined` |
| `count`, `entities` | The number of matched entities and the list of them |
| `archive.status` | `hit` when an archived row was served |

A provider with no id for the entity has no key in `provider_ids`. The match above has no `espn` key, and the team has no `sportradar`, `opta` or `entain` key.

## Use the canonical URN in other calls

The fixture-scoped Match Context operations take the canonical event URN as `event_urn`. They also take the API-Football fixture id as `provider_event_id`.

| Job | Operation | Field | Price |
| --- | --- | --- | --- |
| Context for one match | `POST https://agents.machina.gg/zcj/fwhuudc4di78/world-cup/v1/get-event-context` | `event_urn` | $0.01 |
| Injury reports for a match | `POST https://agents.machina.gg/zcj/fwhuudc4di78/world-cup/v1/get-injuries` | `event_urn` | $0.01 |
| Squads for a match | `POST https://agents.machina.gg/zcj/fwhuudc4di78/world-cup/v1/get-squads` | `event_urn` | $0.01 |
| Player performance in a match | `POST https://agents.machina.gg/zcj/fwhuudc4di78/world-cup/v1/get-player-performance-context` | `event_urn` plus one of `player_urn`, `player` or `player_id`, such as `<player_urn>` | $0.01 |

## Limits

- The archive covers the completed FIFA World Cup 2026 only, and no other competition or season.
- Resolution is exact. The id must match an archived canonical URN or provider id.
- The body takes one `id`. Send one request for each id.
- Each call is one 402 at $0.01. The card rail requires at least $0.50 per pay-as-you-go call, so a single resolve is paid by wallet.

## Errors

| Status | Meaning | Action |
| --- | --- | --- |
| `402` | The price quote. Nothing is charged yet. | Pay and retry the same request, or stop |
| `400` `entity_selector_required`, `entity_ambiguous`, `unsupported_parameter` | The body did not identify one entity, or it used a field the endpoint does not take | Fix the body using `error.accepted_fields` |
| `404` `entity_not_found` | No archived entity matches the id | Check the id and its provider format |
| `503` `archive_row_missing` | A valid id with no archived row | Retry later |
| `502` `archive_error` | An archive integrity error. Nothing was served. | Retry later |

These error answers carry `"billed": false` and are not charged. The code is in `error.reason_code`. [The error reference](https://agents.machina.gg/zcj/fwhuudc4di78/errors.md) covers payment errors.

## Frequently asked questions

### How do I map a Sportradar ID to an Opta ID?

Send the Sportradar id as `id` to `POST https://agents.machina.gg/zcj/fwhuudc4di78/world-cup/v1/resolve` and read `data.entity.provider_ids.opta`. The same response carries the API-Football and Entain ids where they exist, for $0.01 per call.

### How do I map an API-Football ID to a Sportradar ID?

Send the API-Football fixture id, such as `"1489371"`, as `id`. The response returns `provider_ids.sportradar` alongside the canonical event URN.

### Why does a team have no Sportradar or Opta ID?

`provider_ids` lists only the providers that hold an id for that entity. The Brazil team entity carries `api_football` and `espn` ids.

### What does an unknown ID return?

An id that matches no archived entity returns `404` with `reason_code` `entity_not_found` and `"billed": false`. The error envelope has `status` `"error"` and an empty `data`.

### Does the resolve API cover live or other competitions?

No. It serves the completed FIFA World Cup 2026 archive, and every response sets `archive.live` to `false`.

## Keep reading

- [Buyer skill](https://agents.machina.gg/zcj/fwhuudc4di78/SKILL.md): the full purchase flow
- [How to pay](https://agents.machina.gg/zcj/fwhuudc4di78/payment.md): the 402, x402, MPP, card and Credits
- [Match Context API reference](https://agents.machina.gg/zcj/fwhuudc4di78/services/match-context/openapi.json): request and response schemas
- [Error reference](https://agents.machina.gg/zcj/fwhuudc4di78/errors.md): every storefront error code

---

Updated 2026-10-20. All Machina Sports guides: https://agents.machina.gg/guides.md. Storefront: https://agents.machina.gg/zcj/fwhuudc4di78/llms.txt.