> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squadassist.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get future transfer value prediction for a player

> Predict a player's transfer market value after a 3-year simulation by comparing them to historical players with similar attributes and trajectories.

The `POST /get_future_transfer_value` endpoint predicts what a player will be worth at transfer time after a 3-year simulation period. SquadAssist finds comparable historical players — matched on attributes such as rating, potential, position, and club reputation — and projects the player's future value based on how those peers evolved. This endpoint covers the future transfer fee component of the full ROI analysis; you can use it in isolation or as part of your own valuation pipeline. For the complete ROI picture including on-field impact, use `POST /get_roi_analysis` instead.

<Note>
  The simulation always uses the **2025/2026 season** as the starting point and projects **3 years forward**. Season and simulation length are not yet request parameters. Reach out in case this is of importance.
</Note>

## Request

The request body must be a JSON object.

<ParamField body="player_id" type="string" required>
  The SquadAssist player ID. Use `POST /query_player` to look up the ID from a Transfermarkt or Wyscout ID.
</ParamField>

<ParamField body="club_id" type="string" required>
  The SquadAssist club ID for the club the player would be joining. The club's reputation and league context influence the prediction. Use `POST /query_club` to look up the ID.
</ParamField>

<ParamField body="expected_transfer_value" type="number">
  The current transfer fee in the currency specified by `currency_code`. This serves as the baseline value for the prediction. If omitted, SquadAssist calculates an expected fee automatically.
</ParamField>

<ParamField body="currency_code" type="string">
  An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code (e.g. `EUR`, `GBP`, `USD`). The `expected_transfer_value` input is interpreted in this currency, and all monetary output values are returned in this currency alongside their EUR equivalents. Defaults to `EUR`.
</ParamField>

## Response

<ResponseField name="currency" type="string">
  The ISO 4217 currency code for all non-EUR monetary values in the response.
</ResponseField>

<ResponseField name="future_transfer_value" type="integer">
  The predicted market transfer value at the end of the 3-year simulation, in the requested currency.
</ResponseField>

<ResponseField name="future_transfer_value_in_eur" type="integer">
  The predicted market transfer value at the end of the 3-year simulation, in EUR.
</ResponseField>

<ResponseField name="value_category" type="string">
  A category summarising the predicted value trajectory. One of: `"Elite Prospect"`, `"Excellent Opportunity"`, `"Steady Grower"`, `"Stable Value"`, `"Decline"`, or `"Major decline"`.
</ResponseField>

<ResponseField name="probabilities_of_different_outcomes" type="object">
  A probability distribution across all six outcome categories, based on how comparable historical players performed.

  <Expandable title="probabilities_of_different_outcomes fields">
    <ResponseField name="probabilities" type="object">
      A map of outcome category name to probability (0.0–1.0). Keys are `"Elite Prospect"`, `"Excellent Opportunity"`, `"Steady Grower"`, `"Stable Value"`, `"Decline"`, and `"Major decline"`.
    </ResponseField>

    <ResponseField name="sample_size" type="integer or null">
      The number of comparable historical players used to build the probability distribution.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="explanations" type="object">
  Explanatory data about the prediction.

  <Expandable title="explanations fields">
    <ResponseField name="simulation_years" type="integer">
      The number of years simulated. Always `3` in v1.
    </ResponseField>

    <ResponseField name="over_thirthy_years" type="boolean">
      `true` if the player will be over 30 during the simulation period, which affects how the model handles the prediction.
    </ResponseField>

    <ResponseField name="similar_players" type="array">
      The comparable historical players SquadAssist used to build the prediction. Each entry includes:

      * `name` (string): player name
      * `initial_value` (integer): their value at the start of the comparable period, in the requested currency
      * `initial_rating` (integer): their ability rating at the start of the period
      * `initial_potential` (integer): their potential rating at the start of the period
      * `later_transfer_value` (integer): their actual transfer value after the comparable period, in the requested currency
      * `age` (integer): their age at the start of the period
      * `season` (string): the season of the comparable period (e.g. `"2021/2022"`)
      * `position` (string): their position during the comparable period
      * `best_role` (string): their SquadAssist role during the comparable period
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash PowerShell theme={null}
  $headers = @{
      "x-api-key"    = "your API key" # Change
      "Content-Type" = "application/json"
  }

  $body = @{
      "player_id"               = "P01K0WPQJPWZCNCYH1KXHTJ9R31" #Change ID to desired player
      "club_id"                 = "C01JJBVJAPKG8CM7ZA5JF5G84R8" #Change ID to desired buying club
      "expected_transfer_value" = 4000000
      "currency_code"           = "EUR"
  }

  Invoke-RestMethod -Uri "https://api.squadassist.ai/v1/get_future_transfer_value" `
                    -Method Post `
                    -Headers $headers `
                    -Body ($body | ConvertTo-Json)
  ```

  ```python Python theme={null}
  import requests

  # 1. Define the endpoint
  url = "https://api.squadassist.ai/v1/get_future_transfer_value"

  # 2. Set up your headers
  headers = {
      "x-api-key": "your_API_key",  # Replace with your actual key
      "Content-Type": "application/json"
  }

  # 3. Define the data (equivalent to the PowerShell $body)
  payload = {
      "player_id": "P01K0WPQJPWZCNCYH1KXHTJ9R31",
      "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8",
      "expected_transfer_value": 4000000,
      "currency_code": "EUR"
  }

  # 4. Make the POST request
  # Using 'json=payload' tells Python to automatically convert the dict 
  # to a JSON string and set the correct Content-Type.
  response = requests.post(url, headers=headers, json=payload)

  # 5. Output the result
  if response.status_code == 200:
      data = response.json()
      print("Success!")
      print(data)
  else:
      print(f"Error {response.status_code}: {response.text}")
  ```

  ```r R theme={null}
  library(httr2)

  # 1. Define the request
  req <- request("https://api.squadassist.ai/v1/get_future_transfer_value") |>
    req_headers(
      "x-api-key"    = "your_API_key",
      "Content-Type" = "application/json"
    ) |>
    # 2. Add the body as a list
    req_body_json(list(
      player_id               = "P01K0WPQJPWZCNCYH1KXHTJ9R31",
      club_id                 = "C01JJBVJAPKG8CM7ZA5JF5G84R8",
      expected_transfer_value = 4000000,
      currency_code           = "EUR"
    ))

  # 3. Perform and parse
  resp <- req_perform(req)
  future_value_data <- resp_body_json(resp)

  print(future_value_data)
  ```
</CodeGroup>

<CodeGroup>
  ```json Response theme={null}
  {
  	"currency"							  : "EUR",
  	"future_transfer_value"               : 21183800,
  	"future_transfer_value_in_eur"        : 21183800,
  	"value_category"                      : "Elite Prospect",
  	"probabilities_of_different_outcomes" : {
  			"probabilities":[],
  			 "sample_size":32
  			},
  	"explanations": {
  			"over_thirthy_years": False, 
  			"similar_players": [
        				{
          				"name": "Example Player",
          				"initial_value": 3800000,
          				"initial_rating": 67,
          				"initial_potential": 72,
          				"later_transfer_value": 5500000,
          				"age": 24,
          				"season": "2021/2022",
          				"position": "CM",
          				"best_role": "Box-to-box midfielder"
        				},
  					...
      				], 
  			"simulation_years" : 3
  			}
  }
  ```
</CodeGroup>

## Errors

| Status | Body                                                | Cause                                            |
| ------ | --------------------------------------------------- | ------------------------------------------------ |
| `400`  | `{"error": "player_id is required"}`                | `player_id` was not included in the request body |
| `400`  | `{"error": "club_id is required"}`                  | `club_id` was not included in the request body   |
| `400`  | `{"error": "Invalid player_id"}`                    | The `player_id` format is not valid              |
| `400`  | `{"error": "Invalid club_id"}`                      | The `club_id` format is not valid                |
| `400`  | `{"error": "currency_code must be a string"}`       | `currency_code` was provided but is not a string |
| `400`  | `{"error": "<message>"}`                            | The `currency_code` is not a valid ISO 4217 code |
| `403`  | `{"error": "Player is not in the allowed leagues"}` | The player is not in your current coverage       |
| `403`  | `{"error": "Requested club is not allowed"}`        | The `club_id` is not available on your plan      |
| `404`  | `{"error": "Club not found"}`                       | No club was found for the provided `club_id`     |