# 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="https://389206920-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn0oY4dP81ezKSkZC4sfF%2Fuploads%2Fgit-blob-7ecf79292a1e7bb085c50b0012a43d631a44a837%2Fimage.png?alt=media" 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](https://docs.market.thallo.io/api-endpoints/projects) 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](https://docs.market.thallo.io/api-endpoints/projects) 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 %}