# Market

## Overview

Access the Thallo market data via API. The screenshot below is of the marketplace user interface which shows the same data as this endpoint returns:

<figure><img src="/files/UdIuWndh0fqCOeYanitg" alt="Thallo marketplace"><figcaption></figcaption></figure>

## Example cURL Request

```sh
curl --request GET 'https://${BASE_URL}/api/market?page=1&per_page=20' \
--header 'Authorization: Bearer ${API_KEY}'
```

## Endpoint Specification

## Get market data

<mark style="color:blue;">`GET`</mark> `/api/market`

Get all of the available sell orders on the market in real-time

#### Query Parameters

| Name      | Type   | Description                                                                                  |
| --------- | ------ | -------------------------------------------------------------------------------------------- |
| page      | number | For pagination. Which page would you like to be returned? The default value is 1.            |
| per\_page | number | For pagination. How many `project` results you would like per page. The default value is 20. |

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | `Bearer ${API_KEY}` |

{% tabs %}
{% tab title="200: OK " %}
`price_cents` is per tonne. 1 tonne is 1,000,000 grams. Purchases are always made in whole tonnes.

Prices are in USD cents.

{% tabs %}
{% tab title="Example" %}

```json
{
    "projects": [
        {
            "project_id": "003g3ghxs84jlgw5pi",
            "vintages": [
                {
                    "vintage_id": "004fdpkssx2zi9vodm",
                    "vintage_year": 2019,
                    "sell_orders": [
                        {
                            "sell_order_id": "006mcfdyidljqj9bs1",
                            "quantity_grams": "1000000",
                            "price_cents": "1500"
                        }
                    ]
                }
            ]
        }
    ],
    "pagination": {
        "per_page": 20,
        "total_pages": 5,
        "total_items": 100,
        "current_page": 1,
        "previous_page": 1,
        "next_page": 1
    }
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    projects: Array<{
        project_id: string
        vintages: Array<{
            vintage_id: string
            vintage_year: number
            sell_orders: Array<{
                sell_order_id: string
                quantity_grams: string
                price_cents: string
            }>
        }>
    }>
    pagination: {
        per_page: number
        total_pages: number
        total_items: number
        current_page: number
        previous_page: number
        next_page: number
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized Your API key is unrecognized or inactive" %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    message: string
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403:  User does not have `API User` role." %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "error": "Forbidden",
    "message": "Permission denied according to assigned roles.",
    "statusCode": 403
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    message: string
    error: string
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="500: Server error An unexpected error has occurred on the server." %}
{% tabs %}
{% tab title="Example" %}

```json
{
    "statusCode": 500,
    "message": "Internal server error"
}
```

{% endtab %}

{% tab title="Schema" %}

```typescript
{
    statusCode: number
    message: string
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Enriching With Project Data

The market data changes frequently and this endpoint returns the up-to-date market data upon each call. However the data about the carbon offset projects remains relatively static and therefore this data is available in a separate [Project Details](/api-endpoints/projects.md) endpoint in order to keep the market data endpoint lightweight.

Use the `project_id`s returned in the market data and call the [Project Details](/api-endpoints/projects.md) endpoint to retrieve the details of each project.

{% hint style="success" %}
Thallo recommend you cache this project data locally to speed up your application and reduce unnecessary traffic.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.market.thallo.io/api-endpoints/market.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.