# Get Lithium forward price curves

Retrieve forward price curves for the Lithium market.
Forward prices are a standalone resource: they are excluded from `POST /v3/prices/lithium`
and are never linked to another price definition, so no `underlyingPrice` is returned.
**Available filters for Lithium forwards:**
- tenors (month labels such as `M1`, `M12`, resolved against the configured forward tenors)
- products, priceTypes (base filters)
- incoterms, countries, regions, purities, grades, tradeTypes (market-specific)
- codes (exclusive filter - when used, only dateFrom, dateTo and tenors are allowed)

`priceCategories` is not accepted: the category is pinned to Forward Price.
A tenor label that is not configured for any forward definition of the market is rejected
with 400. A label that is valid for the market but absent from the definitions left by the
other filters returns 200 with an empty `curves` array.
**Markets without forward prices:** a market that has no Forward Price definition at all
responds with 404, exactly like an unknown market slug — the forwards resource does not
exist for that market. This is independent of the request filters: a market that does have
forward prices but whose filters match none of them still returns 200 with an empty `data`.
**Unit conversion:** `options.unitOfMeasure` converts mass-family prices between `t`, `kg` and `lb`.

Endpoint: POST /lithium/forwards
Version: 1.0.0
Security: api_key

## Security:

  - `api_key` (unknown)
    apiKey in header x-api-key scopes: prices:lithium

## Request fields (application/json):

  - `filters` (object)
    Base filters for the forward prices endpoint. priceCategories is not exposed because the category is pinned to Forward Price.

  - `filters.codes` (array)
    Exclusive filter - when provided, only dateFrom, dateTo and tenors are allowed.
Filter by specific price codes.
    Example: ["BMIFORWARD_LCMA"]

  - `filters.dateFrom` (string)
    Start of the assessment date range (YYYY-MM-DD)
    Example: 2024-01-01

  - `filters.dateTo` (string)
    End of the assessment date range (YYYY-MM-DD)
    Example: 2024-12-31

  - `filters.products` (array)
    Filter by product names
    Example: ["Lithium Carbonate"]

  - `filters.priceTypes` (array)
    Filter by price types
    Example: ["Price"]

  - `filters.tenors` (array)
    Tenor labels configured for the market forward definitions.
A label unknown to every forward definition of the market is rejected with 400.
    Example: ["M1","M12"]

  - `filters.purities` (array)
    Example: ["Min 99.5%"]

  - `filters.incoterms` (array)
    Example: ["CIF"]

  - `filters.countries` (array)
    Example: ["China"]

  - `filters.regions` (array)
    Example: ["Asia"]

  - `filters.tradeTypes` (array)
    Example: ["Spot"]

  - `filters.grades` (array)
    Example: ["Battery"]

  - `options` (object)
    Options accepted by the forward prices endpoint. There is no includeSeries or includeSummary.

  - `options.curves` (string)
    `all` (default): one curve entry per assessment date within the requested range.
`latest`: a single curve entry built from the most recent assessment per tenor.
    Enum: "latest", "all"

  - `options.currency` (string)
    Target currency for value conversion.
    Example: USD

  - `options.unitOfMeasure` (string)
    Target unit of measure for value conversion.
    Enum: "t", "kg", "lb"

  - `options.includeInternalProperties` (boolean)

  - `options.includeUnpublished` (boolean)

## Request examples:

  - `Every curve in a date range` (unknown)

  - `Single curve built from the most recent assessment per tenor` (unknown)

  - `Restrict the curves to specific tenors` (unknown)

  - `Request by specific forward assessment codes` (unknown)

  - `Convert the curve values to another currency and unit` (unknown)

## Response 200:

  - `200` (unknown)
    Successful response with Lithium forward curves

## Response 200 fields (application/json):

  - `$metadata` (object)

  - `$metadata.market` (string)
    Market display name
    Example: Lithium

  - `data` (array)

  - `data.code` (string)
    Example: BMIFORWARD_LCMA

  - `data.name` (string)
    Example: Lithium; Forward Price; Lithium Carbonate; Min 99.5%; CIF; Asia; Price; USD; Tonne

  - `data.shortName` (string | null)
    Example: Forward Price; Lithium Carbonate; Min 99.5%; CIF Asia; USD; Tonne

  - `data.specification` (array)

  - `data.specification.name` (string)
    Specification attribute name
    Example: Purity

  - `data.specification.value` (string)
    Specification attribute value
    Example: 99.5%

  - `data.specification.order` (integer)
    Display order for the specification
    Example: 1

  - `data.assessmentLaunchedAt` (string | null)
    Example: 2024-01-01

  - `data.lastAssessedAt` (string | null)
    Example: 2024-12-31

  - `data.latestPublishedAt` (string | null)
    Example: 2024-12-31T09:00:00.000Z

  - `data.product` (object)

  - `data.product.id` (string)

  - `data.product.name` (string)

  - `data.product.alias` (string)

  - `data.product.chemicalCode` (string | null)

  - `data.product.isSustainable` (boolean)

  - `data.priceCategory` (object)

  - `data.priceCategory.id` (string)

  - `data.priceCategory.name` (string)

  - `data.frequency` (object)

  - `data.frequency.id` (string)

  - `data.frequency.name` (string)

  - `data.frequency.shortName` (string)

  - `data.unitOfMeasure` (object)

  - `data.unitOfMeasure.id` (string)

  - `data.unitOfMeasure.name` (string)

  - `data.unitOfMeasure.symbol` (string)

  - `data.currency` (object)

  - `data.currency.id` (string)

  - `data.currency.name` (string)

  - `data.currency.iso` (string)

  - `data.currency.symbol` (string)

  - `data.isIoscoAssured` (boolean)
    Example: false

  - `data.curves` (array)
    Always the last property of the item, emitted after every identity and market-specific
attribute. Empty when the definition has no priced rows in the requested range.

  - `data.curves.assessedAt` (string)
    Example: 2024-12-31

  - `data.curves.points` (array)

  - `data.curves.points.tenor` (object)
    Forward tenor position on a curve point (offset + unit ahead of the assessment date).

  - `data.curves.points.tenor.unit` (string)
    Enum: "MONTH"

  - `data.curves.points.tenor.offset` (integer)
    Number of units ahead of the assessment date.
    Example: 1

  - `data.curves.points.tenor.label` (string)
    Human-readable tenor label derived at request time.
    Example: M1

  - `data.curves.points.deliveryDate` (string)
    Assessment date shifted by the tenor offset.
    Example: 2025-01-31

  - `data.curves.points.valueHigh` (number | null)
    Example: 12500

  - `data.curves.points.valueLow` (number | null)
    Example: 11500

  - `data.curves.points.valueMid` (number)
    Example: 12000

## Response 400:

  - `400` (unknown)
    Bad Request - Validation errors

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.location` (string)
    Example: body

  - `errors.code` (string)
    Example: invalid_type

  - `errors.property` (string)
    Example: filters.dateFrom

  - `errors.message` (string)
    Example: Expected string, received array

  - `message` (string)
    Example: Invalid request parameters

## Response 401:

  - `401` (unknown)
    Unauthorized - Missing or invalid authentication

## Response 401 fields (application/json):

  - `code` (string)
    Example: AUTH-0001

  - `message` (string)
    Example: Token expired

## Response 403:

  - `403` (unknown)
    Forbidden - Insufficient permissions

## Response 403 fields (application/json):

  - `code` (string)
    Example: AUTH-0010

  - `message` (string)
    Example: Forbidden

## Response 404:

  - `404` (unknown)
    Not Found - the market does not exist, or it exists but has no Forward Price category at all.
Both cases are reported as 404: the forwards resource simply does not exist for that market.
A market that does have forward prices but whose request filters match nothing returns 200
with an empty `data` array instead.

## Response 404 fields (application/json):

  - `code` (string)
    Example: PA-0095

  - `message` (string)
    Example: The specified market does not have forward prices.

## Response 200 examples:

  - `One curve entry per definition` (unknown)

  - `Definition kept with an empty curve list` (unknown)

## Response 400 examples:

  - `Validation error` (unknown)

  - `Codes filter exclusivity error` (unknown)

## Response 404 examples:

  - `The market exists but has no Forward Price definitions` (unknown)

  - `The market slug is not a known market` (unknown)